Flux 图像生成 API 接入文档

概述

Flux API 提供 BFL FLUX 系列模型的图像生成能力，采用异步任务调用模式：

创建任务：POST 提交生成请求，立即返回 task_id 与查询地址

查询结果：GET 通过 task_id 轮询任务状态，成功后取得图片 URL

鉴权

所有接口均通过 Bearer Token 鉴权：

Authorization: Bearer <your_api_key>

请妥善保管 API Key，不要写在前端代码或公开仓库中。

支持的模型

模型名	系列	用途
`flux-2-max`	FLUX 2	最高画质，推理最慢
`flux-2-pro`	FLUX 2	主力模型，画质/速度平衡
`flux-2-pro-preview`	FLUX 2	滚动更新的 pro 预览版
`flux-2-flex`	FLUX 2	高灵活度控制
`flux-2-klein-4b`	FLUX 2 Klein	轻量快速，4B 参数
`flux-2-klein-9b`	FLUX 2 Klein	中等规模，9B 参数
`flux-2-klein-9b-preview`	FLUX 2 Klein	滚动更新的 9B 预览版
`flux-kontext-pro`	Kontext 编辑	基于参考图的编辑生成
`flux-kontext-max`	Kontext 编辑	Kontext 高质量版
`flux-pro-1.1-ultra`	FLUX 1.x	高分辨率超采样
`flux-pro-1.1`	FLUX 1.x	FLUX 1.1 主力版本
`flux-pro`	FLUX 1.x	FLUX 1.0 经典版
`flux-dev`	FLUX 1.x	开发测试版
`flux-pro-1.0-fill`	Fill 工具	局部重绘 / inpainting
`flux-pro-1.0-expand`	Expand 工具	图像外扩 / outpainting

1. 创建图像任务

Endpoint

POST https://api.ezlinkai.com/flux/v1/{model}

将 {model} 替换为上表中的模型名，例如：

POST https://api.ezlinkai.com/flux/v1/flux-2-pro
POST https://api.ezlinkai.com/flux/v1/flux-2-klein-9b

Request Headers

Header	值	必填	说明
`Authorization`	`Bearer <your_api_key>`	✅	API 密钥
`Content-Type`	`application/json`	✅	请求体格式

Request Body

字段	类型	必填	默认	说明
`prompt`	string	✅	—	图像描述文字
`width`	int	❌	1024	输出宽度，建议 256~1440 之间 32 的倍数
`height`	int	❌	1024	输出高度，建议 256~1440 之间 32 的倍数
`aspect_ratio`	string	❌	—	宽高比，如 `"16:9"`、`"1:1"`、`"4:3"`（部分模型支持，传入后会忽略 width/height）
`seed`	int	❌	随机	随机种子，传入相同 seed + prompt 可复现
`output_format`	string	❌	`"jpeg"`	输出格式：`"jpeg"` / `"png"` / `"webp"`
`safety_tolerance`	int	❌	2	安全审核宽容度，0（最严）~6（最宽），部分模型支持
`prompt_upsampling`	bool	❌	false	是否启用 prompt 自动增强（FLUX 1.x 系列支持）

⚠️ 不同模型支持的可选参数略有差异，传入不支持的参数会被忽略或返回 422。
详细字段请参考模型对应的能力说明。

Request 示例

{
  "prompt": "a cute orange cat sitting on a wooden chair, photorealistic, cinematic lighting",
  "width": 1024,
  "height": 1024,
  "output_format": "jpeg",
  "seed": 42
}

Response

✅ 成功响应（HTTP 200）

{
  "cost": 3,
  "id": "1a572d45-1b93-495e-bc9c-9d7451baf61b",
  "input_mp": 0,
  "output_mp": 0.95,
  "polling_url": "https://api.bfl.ai/v1/get_result?id=1a572d45-1b93-495e-bc9c-9d7451baf61b",
  "status": "processing"
}

字段	类型	说明
`id`	string	任务唯一 ID，请保存用于后续查询
`polling_url`	string	任务结果查询地址，可直接 GET

❌ 失败响应

HTTP	含义	响应示例
400	模型不支持 / 参数非法	`{"error":{"message":"model xxx is not supported"}}`
401	API Key 无效或过期	`{"error":{"message":"invalid token"}}`
402	账户余额不足	`{"error":{"message":"账户余额不足"}}`
422	参数校验失败	`{"error":{"message":"..."}}`
5xx	服务暂时不可用	`{"error":{"message":"..."}}`

curl 示例

2. 查询任务结果

Endpoint

GET https://api.ezlinkai.com/flux/v1/get_result/{id}

将 {id} 替换为创建任务时返回的 id，或直接使用响应中的 polling_url。

Request Headers

Header	值	必填	说明
`Authorization`	`Bearer <your_api_key>`	✅	API 密钥

Path Parameters

参数	类型	必填	说明
`id`	string	✅	创建任务时返回的 task_id

Query Parameters

参数	类型	默认	说明
`from_source`	bool	`false`	`true`：实时查询模式（仅排错使用，响应略慢）；`false`：默认模式（推荐）

Response

查询接口返回 4 种状态：

① 任务成功（图片已就绪）

{
  "id": "abc123-def456-789",
  "status": "Ready",
  "result": {
    "sample": "https://cdn.example.com/output/xxxx.jpg"
  }
}

字段	类型	说明
`status`	string	`"Ready"` 表示任务已完成
`result.sample`	string	生成图片的 URL

⚠️ 图片 URL 有效期约 1 小时，请尽快下载或转存至自有存储（OSS / S3 / CDN）。
过期后链接失效无法恢复。

② 任务进行中

{
  "id": "abc123-def456-789",
  "status": "submitted",
  "error": ""
}

`status` 取值	含义
`submitted`	已提交，等待执行
`processing`	正在生成
`pending`	任务初始化中（罕见，几乎瞬间过渡）

收到上述状态时，请间隔 2~3 秒后再次查询，直到 status 变为 Ready 或 failed。

③ 任务失败

{
  "id": "abc123-def456-789",
  "status": "failed",
  "error": "Content Moderated"
}

常见 error 值：

error 值	原因
`"Content Moderated"` / `"Request Moderated"`	内容审核未通过（prompt 含敏感词等）
`"任务超时"`	任务超过 15 分钟未完成，已自动判定失败
`"Internal Server Error"`	上游服务异常，建议重新提交
其他	上游返回的具体错误信息

④ 任务不存在

HTTP 404
{"error": "task not found"}

任务 ID 错误，或任务记录已被清理。

curl 示例

3. 任务状态机

   pending ──► submitted ──► processing ──► Ready    (✓ 终态：成功)
                  │              │
                  │              └──────────► failed (✗ 终态：失败)
                  │
                  └─────────────────────────► failed

状态	终态	客户端动作
`pending`	✗	继续轮询
`submitted`	✗	继续轮询
`processing`	✗	继续轮询
`Ready`	✓	从 `result.sample` 下载图片
`failed`	✓	读取 `error` 字段，停止轮询

进入终态（Ready / failed）后，多次查询返回的内容一致，不会再变更。

4. 完整集成示例

bash

Python

Node.js (axios)

5. 常见问题

Q1：图片 URL 多久过期？
A：约10分钟。请尽快下载或上传至自有 CDN/对象存储。

Q2：建议的轮询间隔？
A：2~3 秒。

FLUX 2 系列：通常 5~15 秒完成

Klein 系列：通常 3~10 秒完成

FLUX 1.x 系列：通常 10~30 秒完成

Q3：可以传 webhook_url 让自己的服务器接收回调吗？
A：暂不开放。请使用 GET 轮询方式获取结果。

Q4：同一个任务可以查询多少次？
A：任务进入终态（Ready / failed）后，查询次数不受限制；结果不会因多次查询而失效。

Q5：任务超时多久会被自动失败？
A：超过 15 分钟仍未完成的任务会被自动标记为 failed，error 字段为 "任务超时"。

Q6：如何复现同一张图？
A：传入相同的 prompt + seed + width/height 即可（部分模型可能仍有微小差异）。

附录：HTTP 状态码速查

HTTP	触发场景	是否扣费
200	创建任务成功 / 查询任务成功	✅（创建时）
400	模型不支持 / 参数非法	❌
401	API Key 无效	❌
402	余额不足	❌
404	任务不存在	—
422	上游参数校验失败	❌
5xx	服务暂时不可用	❌

Flux

Flux 图像生成 API 接入文档#

概述#

鉴权#

支持的模型#

1. 创建图像任务#

Endpoint#

Request Headers#

Request Body#

Request 示例#

Response#

✅ 成功响应（HTTP 200）#

❌ 失败响应#

curl 示例#

2. 查询任务结果#

Endpoint#

Request Headers#

Path Parameters#

Query Parameters#

Response#

① 任务成功（图片已就绪）#

② 任务进行中#

③ 任务失败#

④ 任务不存在#

curl 示例#

3. 任务状态机#

4. 完整集成示例#

bash#

Python#

Node.js (axios)#

5. 常见问题#

附录：HTTP 状态码速查#

Flux 图像生成 API 接入文档

概述

鉴权

支持的模型

1. 创建图像任务

Endpoint

Request Headers

Request Body

Request 示例

Response

✅ 成功响应（HTTP 200）

❌ 失败响应

curl 示例

2. 查询任务结果

Endpoint

Request Headers

Path Parameters

Query Parameters

Response

① 任务成功（图片已就绪）

② 任务进行中

③ 任务失败

④ 任务不存在

curl 示例

3. 任务状态机

4. 完整集成示例

bash

Python

Node.js (axios)

5. 常见问题

附录：HTTP 状态码速查