ComfyPilotComfyPilot
文档 / 开发 / 配合 Comfy Router 使用 FLUX 3 Image

配合 Comfy Router 使用 FLUX 3 Image

通过 Comfy Router 调用 bfl/flux-3-image：端点、请求形状以及 Router 返回的响应。

开发 code 更新于 2026-10-11

查看官方原文

配合 Comfy Router 使用 FLUX 3 Image

通过 Comfy Router 调用 bfl/flux-3-image：端点、请求形状以及 Router 返回的响应。

由 Black Forest Labs 提供、经 Comfy Router 服务的 bfl/flux-3-image API 参考文档。

输入： 文本, 图像 · 输出： 图像

快速开始

在你的 Comfy 工作区中创建密钥，并将其导出为 COMFY_API_KEY。Python 和 TypeScript 片段使用 Comfy SDK（pip install comfy-sdk 和 npm install @comfyorg/sdk）；cURL 片段是通过原始 HTTP 发出的同一调用。

模型 ID： bfl/flux-3-image

端点： POST https://api.comfy.org/v2/models/bfl/flux-3-image

[tab] 等待结果 ``python Python theme={null} from comfy_sdk import Comfy # 从环境变量读取 COMFY_API_KEY。 # SDK 会自动创建幂等键，并在自动重试时复用它。 with Comfy() as client: result = client.models.run( "bfl/flux-3-image", { "aspect_ratio": "16:9", "prompt": "A mountain landscape at sunset", "resolution": "1k", }, ) print(result) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("bfl/flux-3-image", { aspect_ratio: "16:9", prompt: "A mountain landscape at sunset", resolution: "1k", }); console.log(data); ` `bash cURL theme={null} curl https://api.comfy.org/v2/models/bfl/flux-3-image \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"aspect_ratio\": \"16:9\", \"prompt\": \"A mountain landscape at sunset\", \"resolution\": \"1k\"}" ``
[tab] 先排队，稍后收集 相同的请求体，发送到 POST https://api.comfy.org/v2/models/bfl/flux-3-image/requests。运行一经接纳，Router 就会以 201 和 request_id 作出响应；结果就绪后，可从当前进程或另一个进程收集。排队交付会讲解状态、取消和收集的流程。 ``python Python theme={null} import asyncio from comfy_sdk import AsyncComfy # 从环境变量读取 COMFY_API_KEY。 # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 async def main(): async with AsyncComfy() as client: handle = await client.models.submit( "bfl/flux-3-image", { "aspect_ratio": "16:9", "prompt": "A mountain landscape at sunset", "resolution": "1k", }, ) print("request_id:", handle.request_id) # 配合模型 ID，就是另一个进程所需的全部信息 # 轮询直到请求完成，按服务器给出的 Retry-After 等待。 async for update in handle.iter_events(): print(update.status, update.queue_position) # 提供商自己的负载，与 models.run() 返回的值相同。 # 失败或已取消的请求会在这里抛出类型化的 Router 错误。 result = await handle.get() print(result) asyncio.run(main()) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量读取 COMFY_API_KEY。 // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 const handle = await comfy.models.submit("bfl/flux-3-image", { aspect_ratio: "16:9", prompt: "A mountain landscape at sunset", resolution: "1k", }); console.log("requestId:", handle.requestId); // 配合模型 ID，就是另一个进程所需的全部信息 // 轮询直到请求完成，按服务器给出的 Retry-After 等待。 for await (const update of handle.events()) { console.log(update.status, update.queuePosition); } // 与 models.run() 返回的结果相同。失败或已取消的请求会在这里被拒绝。 const result = await handle.get(); console.log(result.data); ` `bash cURL theme={null} # 1. 提交。Router 以 201 响应，并返回 request_id、status_url、response_url 和 cancel_url。 curl https://api.comfy.org/v2/models/bfl/flux-3-image/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"aspect_ratio\": \"16:9\", \"prompt\": \"A mountain landscape at sunset\", \"resolution\": \"1k\"}" # 2. 轮询直到状态为 COMPLETED，按每个响应给出的 Retry-After 秒数等待。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/bfl/flux-3-image/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。返回 200 时是模型的原生输出，仍在运行时返回 202 和状态正文。 curl https://api.comfy.org/v2/models/bfl/flux-3-image/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

aspect\_ratio string (default: "auto")

输出宽高比：auto、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 会跟随该图像。

grounding boolean (default: true)

让模型在生成之前通过搜索和图像搜索来研究提示词。设为 false 可同时关闭这两项。

images string | string[]

提示词所编辑或参考的一到十张图像，每张为 http(s) URL 或 base64 字符串。单个字符串会被视为只含一项的列表。每张图像至少为 256x256 像素、至多 16 百万像素，base64 载荷至多 20 MB；输入会被缩放到最接近的分辨率档位，最高 2k。

prompt string required

要生成的图像的文本描述，或要对参考图像应用的编辑的文本描述。

resolution string (default: "1k")

输出分辨率档位：768sq、1k、1.5k、2k 或 4k。

safety\_tolerance integer (default: 2)

输入和输出审核的阈值等级，0 为最严格。

范围：0 到 4

version string (default: "latest")

端点版本。latest 提供当前发布的版本；带日期的可固定发布标签会随其发布陆续加入。

由 Router 在 GET /v2/models/bfl/flux-3-image/openapi.json 提供的 schema 生成，与它在请求到达提供商之前用于校验调用的文档是同一份。

输出

cost number

提供商报告的以积分计的费用，任务进入 Ready 后填入。

格式：float

id string required

BFL 任务标识符。

progress number

BFL 报告的生成进度，可选。

范围：0 到 1

格式：float

result object required

已完成的生成结果。此处不可为 null：该组件的 required 条目承诺 200 会携带结果，而可为 null 的 result 会把它降级为仅检查键是否存在。

result.cost number

提供商报告的本次生成费用。这是 BFL 的数值，不是 Comfy 的收费。

格式：double

result.duration number

提供商报告的生成时长，单位为秒。

格式：double

result.end\_time number

提供商报告的本次生成完成时间，为自 Unix 纪元起的秒数。与 start_time 一样使用 double。

格式：double

result.prompt string

本次生成实际执行的提示词，即经过任何提示词上采样之后的提示词。

result.sample string (uri)

已生成资产的签名 URL。Router 会把该资产重新托管到 Comfy 存储并改写此字段，因此它通常是 Comfy 托管的 URL，有效期最长 24 小时：签发时按 24 小时签名，并从 23 小时的备忘中重放，因此稍后轮询可能返回一个仅剩一小时有效期的 URL；某个无法执行重新托管的叶子节点则会保留 BFL 自己的短时效分发 URL，视频约为两小时，图像约为十分钟。无论哪种情况，链接都会过期，因此请下载资产，而不要保存该 URL。

格式：uri

result.seed integer

本次生成使用的种子，无论是提供的还是由提供商选择的。声明为 int64，因为 BFL 会返回大于 2^31 的种子（例如 2784347701），而在许多 SDK 生成器中，未格式化的 integer 会被生成为 32 位字段。

格式：int64

result.start\_time number

提供商报告的本次生成开始时间，为自 Unix 纪元起的秒数。使用 double 而非 float：在当今的纪元数值附近，float32 的间距约为 128 秒，这会把整次生成的跨度压缩成一个解码值。

格式：double

status string required

任务状态：Pending、Reasoning、Generating、Ready、Request Moderated、Content Moderated、Error 或 Task not found。

示例

输入

{
  "aspect_ratio": "16:9",
  "prompt": "A mountain landscape at sunset",
  "resolution": "1k"
}

输出

{
  "cost": null,
  "id": "b2e0c1a4-0f2f-4a55-9f2e-2f9a1c0d4e77",
  "progress": null,
  "result": {
    "cost": null,
    "duration": 3.4,
    "end_time": 1767225603.4,
    "prompt": "A watercolor painting of a lighthouse at dawn, soft light on the water",
    "sample": "https://example.invalid/bfl/flux-pro-1.1/sample.png",
    "seed": 2784347701,
    "start_time": 1767225600
  },
  "status": "Ready"
}

发布前须知

SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。

请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。

本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。

[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
[card] 使用 Router API 模型发现、验证错误、重试与计费。
[card] 限制 Router 目前不支持的功能，以及替代方案。