ComfyPilotComfyPilot
文档 / 开发 / 使用 Comfy Router 调用 FLUX 2 Max

使用 Comfy Router 调用 FLUX 2 Max

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

开发 code 更新于 2026-10-11

查看官方原文

使用 Comfy Router 调用 FLUX 2 Max

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

bfl/flux-2-max 的 API 参考文档，由 Comfy Router 提供，来自 Black Forest Labs。

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

快速开始

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

模型 ID： bfl/flux-2-max

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

[tab] 等待结果 ``python Python theme={null} from comfy_sdk import Comfy # 从环境变量中读取 COMFY_API_KEY。 # SDK 会自动创建幂等键，并在自动重试时复用它。 with Comfy() as client: result = client.models.run( "bfl/flux-2-max", { "prompt": "A single red maple leaf on a plain white background.", }, ) print(result) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("bfl/flux-2-max", { prompt: "A single red maple leaf on a plain white background.", }); console.log(data); ` `bash cURL theme={null} curl https://api.comfy.org/v2/models/bfl/flux-2-max \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"prompt\": \"A single red maple leaf on a plain white background.\"}" ``
[tab] 先入队，稍后收集 将相同的请求体发送到 POST https://api.comfy.org/v2/models/bfl/flux-2-max/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-2-max", { "prompt": "A single red maple leaf on a plain white background.", }, ) 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-2-max", { prompt: "A single red maple leaf on a plain white background.", }); 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-2-max/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"prompt\": \"A single red maple leaf on a plain white background.\"}" # 2. 轮询直到状态为 COMPLETED，并按每个响应指定的 Retry-After 秒数等待。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/bfl/flux-2-max/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。返回 200 时携带模型的原始输出；仍在运行时返回 202 及状态响应体。 curl https://api.comfy.org/v2/models/bfl/flux-2-max/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

height integer (default: 1024)

图像的高度。

范围：256 到 2048

input\_image string

Base64 编码的图像，用于图生图生成。

input\_image\_2 string

Base64 编码的图像，用于图生图生成。

input\_image\_3 string

Base64 编码的图像，用于图生图生成。

input\_image\_4 string

Base64 编码的图像，用于图生图生成。

input\_image\_5 string

Base64 编码的图像，用于图生图生成。

input\_image\_6 string

Base64 编码的图像，用于图生图生成。

input\_image\_7 string

Base64 编码的图像，用于图生图生成。

input\_image\_8 string

Base64 编码的图像，用于图生图生成。

input\_image\_9 string

Base64 编码的图像，用于图生图生成。

output\_format string (default: "jpeg")

已生成图像的输出格式。

可选值：jpeg、png

prompt string required

要生成的图像的文本描述。

prompt\_upsampling boolean (default: true)

自动修改用于生成的提示词。

safety\_tolerance integer (default: 2)

审核阈值等级（仅 Flux 2 Max）。

范围：0 到 5

seed integer

用于复现的种子。

width integer (default: 1024)

图像的宽度。

范围：256 到 2048

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

输出

cost number

提供商报告的积分成本，在任务变为 Ready 后填充。

格式：float

id string required

BFL 任务标识符。

progress number

BFL 报告的可选生成进度。

范围：0 到 1

格式：float

result object required

已完成的生成结果。此处不可为空：该组件的 required 条目是一份承诺，即 200 响应必定携带结果，而可为空的 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 小时的缓存中重放，所以稍后的轮询可能返回一个仅剩一小时的链接；对于无法执行重新托管的叶子节点，则保留 BFL 自己的短时效投放 URL，视频大约两小时，图像大约十分钟。无论哪种情况，链接都会过期，因此请下载资产，而不要保存该 URL。

格式：uri

result.seed integer

该次生成所使用的种子，无论是外部提供还是由提供商选择。声明为 int64，是因为 BFL 会返回大于 2^31 的种子（例如 2784347701），而未加格式限定的 integer 在许多 SDK 生成器中会生成 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。

示例

输入

{
  "prompt": "A single red maple leaf on a plain white background."
}

输出

{
  "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 目前不支持的功能，以及替代方案。