FLUX API

模型简介

Exchange Token 通过以下路径提供 FLUX 图像生成能力：

• POST /v1/flux-2-pro
• POST /v1/flux-2-max
• POST /v1/flux-3-image

先提交生成任务，再通过返回的 polling_url 或 GET /v1/get_result?id=... 轮询结果。

调用方式

API 端点

https://api.exchangetoken.ai

认证方式

FLUX 接口使用以下认证头：

x-key: YOUR_API_KEY

也可以使用 Authorization: Bearer YOUR_API_KEY。创建任务和查询结果须使用同一个 API Key。

请求格式

Content-Type: application/json

提交任务

FLUX 2 pro/max 请求

使用 POST /v1/flux-2-pro 或 POST /v1/flux-2-max。

Request 字段

字段	类型	必填	说明
prompt	string	是	图像生成或编辑提示词
input_image	string	否	第一张参考图，使用可访问的图片 URL 或 Base64；文生图时省略
input_image_2 到 input_image_8	string	否	第 2–8 张参考图，每个字段一张图片
seed	integer	否	随机种子，用于复现结果；例如 42
width	integer	否	输出宽度，单位像素；显式指定时至少为 64
height	integer	否	输出高度，单位像素；显式指定时至少为 64
safety_tolerance	integer	否	当前接口接受 0–5，0 最严格
output_format	string	否	输出图片格式，使用 jpeg 或 png

FLUX 3 Image 请求

使用 POST /v1/flux-3-image。

Request 字段

字段	类型	必填	说明
prompt	string	是	图像生成或编辑提示词，不能为空或仅含空白
images	string 或 string[]	否	1–10 张参考图，支持 HTTP(S) URL 或 Base64；无参考图时省略此字段，不传 null 或空数组
resolution	string	否	分辨率档位：768sq、1k、1.5k、2k、4k；默认 1k
aspect_ratio	string	否	输出宽高比，默认 auto；可选值见下文
grounding	boolean	否	是否启用网页和图片搜索；false 表示关闭
safety_tolerance	integer	否	当前接口接受 0–4，0 最严格

aspect_ratio 支持：21:9、2:1、16:9、3:2、7:5、4:3、5:4、1:1、4:5、3:4、5:7、2:3、9:16、1:2、9:21、auto。

Response

字段	类型	说明
id	string	平台任务 ID，用于后续查询
polling_url	string	查询结果的完整 URL，使用相同 API Key 发起 GET 请求

查询任务结果

Request 字段

GET /v1/get_result?id=TASK_ID

字段	位置	类型	必填	说明
id	Query	string	是	提交响应中的任务 ID

Response 字段

字段	类型	说明
id	string	平台任务 ID
status	string	当前返回 Pending、Ready 或 Error
result	object 或 null	成功时包含 sample；处理中或失败时为 null
result.sample	string	生成图片的完整 URL
progress	number	可选进度字段，没有可用进度时省略
details	object[]	可选失败详情，每项仅包含 msg
details[].msg	string	失败原因

平台错误响应

请求未通过 Exchange Token 平台校验，或 Exchange Token 平台无法完成请求处理时，返回 HTTP 4xx 或 5xx 状态码，响应体采用以下结构：

字段	类型	说明
error	object	平台错误信息
error.type	string	错误类型，例如 invalid_request、rate_limited
error.message	string	错误原因的详细说明

常见 HTTP 状态码：

状态码	说明
400	请求参数不合法或缺少必填参数
401	API Key 缺失或无效
402	可用额度不足
403	访问被拒绝，例如 API Key 已禁用、已过期或 IP 不在允许范围内
404	查询的任务不存在或不属于当前 API Key
429	超出请求频率或并发限制
500	平台内部处理失败
502	上游通信失败或响应不符合接口要求
503	服务暂不可用，例如没有可用渠道

示例

提交生成任务

FLUX 2 pro 文生图

curl -X POST "https://api.exchangetoken.ai/v1/flux-2-pro" \
  -H "x-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic portrait of a silver robot walking in neon rain",
    "width": 1024,
    "height": 1024,
    "seed": 42,
    "safety_tolerance": 2,
    "output_format": "png"
  }'

FLUX 2 max 多图参考

请将示例 URL 替换为可访问的图片地址。

curl -X POST "https://api.exchangetoken.ai/v1/flux-2-max" \
  -H "x-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "保留第一张图的茶壶造型，使用第二张图的配色，置于木质桌面上",
    "input_image": "https://example.com/teapot.png",
    "input_image_2": "https://example.com/color-reference.png",
    "width": 1024,
    "height": 1024,
    "output_format": "png"
  }'

FLUX 3 Image 文生图

curl -X POST "https://api.exchangetoken.ai/v1/flux-3-image" \
  -H "x-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只蓝色陶瓷茶壶，摄影棚光照，纯白背景",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "grounding": false,
    "safety_tolerance": 2
  }'

FLUX 3 Image 参考图生成

请将示例 URL 替换为可访问的图片地址。

curl -X POST "https://api.exchangetoken.ai/v1/flux-3-image" \
  -H "x-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "保留第一张图的茶壶造型，使用第二张图的配色，置于木质桌面上",
    "images": [
      "https://example.com/teapot.png",
      "https://example.com/color-reference.png"
    ],
    "resolution": "1k",
    "aspect_ratio": "4:3"
  }'

Response

{
  "id": "sg_img_123456",
  "polling_url": "https://api.exchangetoken.ai/v1/get_result?id=sg_img_123456"
}

查询任务结果

将 id 替换为提交响应中的任务 ID。

curl "https://api.exchangetoken.ai/v1/get_result?id=sg_img_123456" \
  -H "x-key: YOUR_API_KEY"

使用同一个任务 ID 轮询，直到 status 变为 Ready 或 Error。

处理中 Response 示例

{
  "id": "sg_img_123456",
  "status": "Pending",
  "result": null,
  "progress": 0.45
}

完成 Response 示例

{
  "id": "sg_img_123456",
  "status": "Ready",
  "result": {
    "sample": "https://cdn.example.com/generated-image.png?signature=example"
  }
}

读取 result.sample 获取图片，下载时保留 URL 的完整查询参数。

错误响应

平台参数错误

FLUX 3 请求中的 resolution 不在允许范围内时，返回 HTTP 400：

{
  "error": {
    "type": "invalid_request",
    "message": "FLUX 3 resolution must be one of 768sq, 1k, 1.5k, 2k, 4k"
  }
}

上游任务错误

查询到任务执行失败时，返回 HTTP 200，details[0].msg 为上游返回的错误消息：

{
  "id": "sg_img_123456",
  "status": "Error",
  "result": null,
  "details": [
    {
      "msg": "image generation failed"
    }
  ]
}