使用 Flux 1.1 Pro Ultra Image 与 Comfy Router

通过 Comfy Router 调用 FLUX 1.1 [pro] Ultra 和 FLUX 1.1 [pro] 的 Python、TypeScript 与 cURL 代码片段，以及请求字段和结果结构

Flux 1.1 Pro Ultra Image 的 API 参考。FLUX 1.1 \[pro] 是 Black Forest Labs 推出的文生图模型。Ultra 模式可生成最高 4MP 分辨率的图像。

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

快速开始

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

选择你要调用的模型。以下所有内容，从代码片段到 schema 和示例，都会随你的选择而变化。

[tab] FLUX 1.1 \[pro] Ultra 模型 ID： bfl/flux-pro-1.1-ultra 端点： POST https://api.comfy.org/v2/models/bfl/flux-pro-1.1-ultra > [tab] 等待结果 > > ``python Python theme={null} > import asyncio > from comfy_sdk import AsyncComfy > > # 从环境中读取 COMFY_API_KEY。 > # SDK 会自动创建幂等键，并在自动重试时复用它。 > async def main(): > async with AsyncComfy() as client: > result = await client.models.run( > "bfl/flux-pro-1.1-ultra", > { > "prompt": "a single red maple leaf on a plain white background, studio lighting", > "aspect_ratio": "16:9", > "raw": False, > }, > ) > > print("image:", result["result"]["sample"]) > > asyncio.run(main()) > ` > > `typescript TypeScript theme={null} > import { comfy } from "@comfyorg/sdk"; > > // 从环境中读取 COMFY_API_KEY。 > // SDK 会自动创建幂等键，并在自动重试时复用它。 > type Result = { result: { sample: string } }; > const result = await comfy.models.run<Result>("bfl/flux-pro-1.1-ultra", { > prompt: "a single red maple leaf on a plain white background, studio lighting", > aspect_ratio: "16:9", > raw: false, > }); > if (result.kind !== "json") throw new Error("expected a JSON result"); > > console.log("image:", result.data.result.sample); > ` > > `bash cURL theme={null} > curl https://api.comfy.org/v2/models/bfl/flux-pro-1.1-ultra \ > -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, studio lighting\", \"aspect_ratio\": \"16:9\", \"raw\": false}" > ` > [tab] 排队并稍后收集 > > 将相同的请求体发送到 POST https://api.comfy.org/v2/models/bfl/flux-pro-1.1-ultra/requests。运行被受理后，Router 会立即返回 201 和 request_id；结果就绪后，可以从本进程或其他进程收集。状态、取消与收集的细节见 [队列投递](https://docs.comfy.org/zh/development/comfy-router/queue.md)。 > > `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-pro-1.1-ultra", > { > "prompt": "a single red maple leaf on a plain white background, studio lighting", > "aspect_ratio": "16:9", > "raw": False, > }, > ) > 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("image:", result["result"]["sample"]) > > asyncio.run(main()) > ` > > `typescript TypeScript theme={null} > import { comfy } from "@comfyorg/sdk"; > > // 从环境中读取 COMFY_API_KEY。 > // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 > type Result = { result: { sample: string } }; > const handle = await comfy.models.submit<Result>("bfl/flux-pro-1.1-ultra", { > prompt: "a single red maple leaf on a plain white background, studio lighting", > aspect_ratio: "16:9", > raw: false, > }); > 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(); > if (result.kind !== "json") throw new Error("expected a JSON result"); > > console.log("image:", result.data.result.sample); > ` > > `bash cURL theme={null} > # 1. 提交。Router 返回 201，并带有 request_id、status_url、response_url 和 cancel_url。 > curl https://api.comfy.org/v2/models/bfl/flux-pro-1.1-ultra/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, studio lighting\", \"aspect_ratio\": \"16:9\", \"raw\": false}" > > # 2. 轮询直到状态为 COMPLETED，按每个响应给出的 Retry-After 秒数等待。 > REQUEST_ID="<request_id from the 201 body>" > curl -i https://api.comfy.org/v2/models/bfl/flux-pro-1.1-ultra/requests/$REQUEST_ID/status \ > -H "X-API-Key: $COMFY_API_KEY" > > # 3. 收集。返回 200 及模型的原始输出；仍在运行时返回 202 及状态正文。 > curl https://api.comfy.org/v2/models/bfl/flux-pro-1.1-ultra/requests/$REQUEST_ID \ > -H "X-API-Key: $COMFY_API_KEY" > ` ## Schema ### 输入 **aspect\_ratio** string (default: "16:9") 图像的比例，介于 21:9 和 9:21 之间，例如 16:9。 **image\_prompt** string 可选的 base64 编码图像，用于混合生成。 **image\_prompt\_strength** number (default: 0.1) 提示词与图像提示词之间的混合程度，从 0（仅使用提示词）到 1（仅使用图像提示词）。 范围：0 到 1 **output\_format** string (default: "jpeg") 输出图像格式。 可选值：jpeg、png、webp **prompt** string *required* 用于图像生成的文本提示词。 **prompt\_upsampling** boolean (default: false) 是否对提示词进行上采样。启用后，提示词会被自动修改，以进行更具创造性的生成。 **raw** boolean (default: false) 生成处理更少、看起来更自然的图像。 **safety\_tolerance** integer (default: 2) 输入和输出审核的容差级别，介于 0（最严格）和 6（最宽松）之间。 范围：0 到 6 **seed** integer 可选种子，用于保证可复现性。省略时使用随机种子。 **webhook\_secret** string 可选密钥，用于 Webhook 签名验证。 **webhook\_url** string (uri) 接收 Webhook 通知的 URL。 格式：uri 根据 Router 在 GET /v2/models/bfl/flux-pro-1.1-ultra/openapi.json 提供的 schema 生成，Router 在请求到达提供商之前会依据同一份文档校验调用。 ### 输出 **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。 ## 示例 ### 输入 `json theme={null} { "prompt": "a single red maple leaf on a plain white background, studio lighting", "aspect_ratio": "16:9", "raw": false } ` ### 输出 `json theme={null} { "id": "0a1b2c3d-...", "status": "Ready", "result": { "sample": "https://.../out.jpeg", "prompt": "a single red maple leaf on a plain white background, studio lighting", "seed": 1234567890 } } `` 该 URL 是临时的。如果你需要保留图像，请及时下载。

[tab] FLUX 1.1 \[pro] 模型 ID： bfl/flux-pro-1.1 端点： POST https://api.comfy.org/v2/models/bfl/flux-pro-1.1 > [tab] 等待结果 > > ``python Python theme={null} > import asyncio > from comfy_sdk import AsyncComfy > > # 从环境中读取 COMFY_API_KEY。 > # SDK 会自动创建幂等键，并在自动重试时复用它。 > async def main(): > async with AsyncComfy() as client: > result = await client.models.run( > "bfl/flux-pro-1.1", > { > "prompt": "a single red maple leaf on a plain white background, studio lighting", > "width": 1024, > "height": 768, > }, > ) > > print("image:", result["result"]["sample"]) > > asyncio.run(main()) > ` > > `typescript TypeScript theme={null} > import { comfy } from "@comfyorg/sdk"; > > // 从环境中读取 COMFY_API_KEY。 > // SDK 会自动创建幂等键，并在自动重试时复用它。 > type Result = { result: { sample: string } }; > const result = await comfy.models.run<Result>("bfl/flux-pro-1.1", { > prompt: "a single red maple leaf on a plain white background, studio lighting", > width: 1024, > height: 768, > }); > if (result.kind !== "json") throw new Error("expected a JSON result"); > > console.log("image:", result.data.result.sample); > ` > > `bash cURL theme={null} > curl https://api.comfy.org/v2/models/bfl/flux-pro-1.1 \ > -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, studio lighting\", \"width\": 1024, \"height\": 768}" > ` > [tab] 排队并稍后收集 > > 将相同的请求体发送到 POST https://api.comfy.org/v2/models/bfl/flux-pro-1.1/requests。运行被受理后，Router 会立即返回 201 和 request_id；结果就绪后，可以从本进程或其他进程收集。状态、取消与收集的细节见 [队列投递](https://docs.comfy.org/zh/development/comfy-router/queue.md)。 > > `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-pro-1.1", > { > "prompt": "a single red maple leaf on a plain white background, studio lighting", > "width": 1024, > "height": 768, > }, > ) > 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("image:", result["result"]["sample"]) > > asyncio.run(main()) > ` > > `typescript TypeScript theme={null} > import { comfy } from "@comfyorg/sdk"; > > // 从环境中读取 COMFY_API_KEY。 > // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 > type Result = { result: { sample: string } }; > const handle = await comfy.models.submit<Result>("bfl/flux-pro-1.1", { > prompt: "a single red maple leaf on a plain white background, studio lighting", > width: 1024, > height: 768, > }); > 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(); > if (result.kind !== "json") throw new Error("expected a JSON result"); > > console.log("image:", result.data.result.sample); > ` > > `bash cURL theme={null} > # 1. 提交。Router 返回 201，并带有 request_id、status_url、response_url 和 cancel_url。 > curl https://api.comfy.org/v2/models/bfl/flux-pro-1.1/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, studio lighting\", \"width\": 1024, \"height\": 768}" > > # 2. 轮询直到状态为 COMPLETED，按每个响应给出的 Retry-After 秒数等待。 > REQUEST_ID="<request_id from the 201 body>" > curl -i https://api.comfy.org/v2/models/bfl/flux-pro-1.1/requests/$REQUEST_ID/status \ > -H "X-API-Key: $COMFY_API_KEY" > > # 3. 收集。返回 200 及模型的原始输出；仍在运行时返回 202 及状态正文。 > curl https://api.comfy.org/v2/models/bfl/flux-pro-1.1/requests/$REQUEST_ID \ > -H "X-API-Key: $COMFY_API_KEY" > ` ## Schema ### 输入 **height** integer (default: 768) 已生成图像的高度，单位为像素。必须是 32 的倍数。 范围：256 到 1440 **image\_prompt** string 可选的 base64 编码图像，用于配合 FLUX Redux 使用。 **output\_format** string (default: "jpeg") 输出图像格式。 可选值：jpeg、png、webp **prompt** string *required* 用于图像生成的文本提示词。 **prompt\_upsampling** boolean (default: false) 是否对提示词进行上采样。启用后，提示词会被自动修改，以进行更具创造性的生成。 **safety\_tolerance** integer (default: 2) 输入和输出审核的容差级别，介于 0（最严格）和 6（最宽松）之间。 范围：0 到 6 **seed** integer 可选种子，用于保证可复现性。省略时使用随机种子。 **webhook\_secret** string 可选密钥，用于 Webhook 签名验证。 **webhook\_url** string (uri) 接收 Webhook 通知的 URL。 格式：uri **width** integer (default: 1024) 已生成图像的宽度，单位为像素。必须是 32 的倍数。 范围：256 到 1440 根据 Router 在 GET /v2/models/bfl/flux-pro-1.1/openapi.json 提供的 schema 生成，Router 在请求到达提供商之前会依据同一份文档校验调用。 ### 输出 **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。 ## 示例 ### 输入 `json theme={null} { "prompt": "a single red maple leaf on a plain white background, studio lighting", "width": 1024, "height": 768 } ` ### 输出 `json theme={null} { "id": "0a1b2c3d-...", "status": "Ready", "result": { "sample": "https://.../out.jpeg", "prompt": "a single red maple leaf on a plain white background, studio lighting", "seed": 1234567890 } } `` 该 URL 是临时的。如果你需要保留图像，请及时下载。

发布前须知

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