ComfyPilotComfyPilot
文档 / 开发 / 使用 Comfy Router 调用 FLUX 3 Video

使用 Comfy Router 调用 FLUX 3 Video

通过 Comfy Router 以 HTTP 方式调用 FLUX 3 生成带同步音频的视频，包含 Python、TypeScript 和 cURL 代码片段，以及请求字段和结果结构

开发 code 更新于 2026-10-21

查看官方原文

使用 Comfy Router 调用 FLUX 3 Video

通过 Comfy Router 以 HTTP 方式调用 FLUX 3 生成带同步音频的视频，包含 Python、TypeScript 和 cURL 代码片段，以及请求字段和结果结构

FLUX 3 Video 的 API 参考。FLUX 3 Video 是 Black Forest Labs 的视频生成模型，可将文本提示词转换为带有同步音频的短片。

输入： 文本, 图像 · 输出： 视频 + 音频

快速开始

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

模型 ID： bfl/flux-3-video

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

[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-3-video", { "mode": "t2v", "prompt": "a single red maple leaf falling onto still water, slow motion", "duration": 5, "aspect_ratio": "16:9", "generate_audio": True, }, ) print("video:", 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-3-video", { mode: "t2v", prompt: "a single red maple leaf falling onto still water, slow motion", duration: 5, aspect_ratio: "16:9", generate_audio: true, }); if (result.kind !== "json") throw new Error("expected a JSON result"); console.log("video:", result.data.result.sample); ` `bash cURL theme={null} curl https://api.comfy.org/v2/models/bfl/flux-3-video \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"mode\": \"t2v\", \"prompt\": \"a single red maple leaf falling onto still water, slow motion\", \"duration\": 5, \"aspect_ratio\": \"16:9\", \"generate_audio\": true}" ``
[tab] 排队并在稍后收集 相同的请求体，发送到 POST https://api.comfy.org/v2/models/bfl/flux-3-video/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-video", { "mode": "t2v", "prompt": "a single red maple leaf falling onto still water, slow motion", "duration": 5, "aspect_ratio": "16:9", "generate_audio": True, }, ) 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("video:", 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-3-video", { mode: "t2v", prompt: "a single red maple leaf falling onto still water, slow motion", duration: 5, aspect_ratio: "16:9", generate_audio: true, }); 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("video:", 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-3-video/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"mode\": \"t2v\", \"prompt\": \"a single red maple leaf falling onto still water, slow motion\", \"duration\": 5, \"aspect_ratio\": \"16:9\", \"generate_audio\": true}" # 2. 轮询直到状态为 COMPLETED，每次等待响应中指定的 Retry-After 秒数。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/bfl/flux-3-video/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。完成时返回 200 和模型的原生输出，仍在运行时返回 202 和状态响应体。 curl https://api.comfy.org/v2/models/bfl/flux-3-video/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

aspect\_ratio string (default: "auto")

输出宽高比：auto、21:9、2:1、16:9、4:3、1:1、3:4 或 9:16。auto 会让 BFL 根据提示词和任何参考素材自行选择。

draft boolean (default: false)

草稿模式：生成一份快速预览，其结果中包含一个 draft\_cache 下载 URL。将该包连同 mode draft\_enhance 一起发回，即可渲染同一次生成的完整质量版本。

draft\_cache string

仅 draft\_enhance 使用。来自先前草稿生成的加密草稿缓存包，形式为 base64 编码的已下载包，或仍然有效的 http(s) URL。原始输入已嵌入该包中。

duration integer | string (default: "auto")

视频时长（秒），可为 5 到 20 之间的任意整数秒，或使用 auto 自动适配内容。

范围：5 到 20

generate\_audio boolean (default: true)

在生成视频的同时生成同步音频。

keyframes string | number | string[] | string[] | number | string[][]

仅 i2v 使用。将成为视频帧的图像，每张为 http(s) URL 或 base64，总共一到十张。接受单张图像、图像列表（一张用于开始视频，两张分别作为起始和结束，更多则均匀分布且需要设定时长），或按时间顺序排列的带时间戳的 \[秒数, 图像] 对，例如 \[\[0, "..."], \[3.5, "..."]]。每个对是包含两个元素的数组：先是秒数，然后是图像。

mode string required

生成模式：t2v（文生视频）、i2v（图像续写）、v2v（视频续写）或 draft\_enhance（对先前草稿进行完整质量渲染）。也接受 text-to-video 这类完整拼写的别名。

prompt string

描述视频的自由格式提示词。除 draft\_enhance 外的所有模式均必填。

resolution string

视频分辨率档位：hd（720p），或 fhd（1080p）、qhd（2K）、uhd（4K），后三者由视频放大器完成更高分辨率的结果。t2v、i2v 和 v2v 默认为 hd，draft\_enhance 默认为 fhd。具体尺寸会随宽高比变化。

可选值：hd、fhd、qhd、uhd

safety\_tolerance integer (default: 2)

输入与输出有害内容审核的阈值级别，0 为最严格。无论请求的阈值如何，色情内容均限制为级别 3，仇恨内容均限制为级别 2；带条件媒体的请求限制为级别 2。

范围：0 到 4

start\_video string

仅 v2v 使用。要续接的视频，为 http(s) URL 或 base64 MP4；生成的视频片段将从其最后几帧继续。

version string (default: "latest")

端点版本。latest 提供当前发布版本；带日期的可固定发布标签会在发布时添加。

本文件生成自 Router 在 GET /v2/models/bfl/flux-3-video/openapi.json 提供的 Schema，也就是在请求到达提供商之前 Router 用于校验调用的同一份文档。

输出

cost number

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

格式：float

id string required

BFL 任务标识符。

progress number

BFL 报告的可选生成进度。

范围：0 到 1

格式：float

result object required

已完成的生成结果。两个 URL 叶子字段中恰好会填充其中一个：默认模式下为 sample，draft: true 模式下为 draft_cache。

result.cost number

提供商报告的任务成本。这是 BFL 的数值，而不是 Comfy 的收费。

格式：double

result.draft\_cache string (uri)

由 draft: true 模式返回、用于替代 sample 的签名 URL，其重新托管到 Comfy 存储的方式与 sample 相同：通常是有效期最长 24 小时的 Comfy 托管 URL；若无法完成重新托管，则为 BFL 自身约两小时有效的交付 URL。

格式：uri

result.sample string (uri)

已生成 MP4 的签名 URL。Router 会把该资源重新托管到 Comfy 存储并重写此字段，因此它通常是有效期最长 24 小时的 Comfy 托管 URL：签发时按 24 小时签名，之后从 23 小时的备忘记录中重放，所以后续轮询可能只拿到仅剩一小时有效期的链接；若某个叶子字段无法完成重新托管，则保留 BFL 自身约两小时有效的交付 URL。在 draft: true 模式下不存在。

格式：uri

status string required

任务状态：Pending、Reasoning、Generating、Ready、Request Moderated、Content Moderated、Error 或 Task not found。比较时不区分大小写；Router 会原样转发 BFL 的拼写。

示例

输入

{
  "mode": "t2v",
  "prompt": "a single red maple leaf falling onto still water, slow motion",
  "duration": 5,
  "aspect_ratio": "16:9",
  "generate_audio": true
}

输出

{
  "id": "0a1b2c3d-...",
  "status": "Ready",
  "result": {
    "sample": "https://.../out.mp4"
  }
}

result.sample 通常是一个由 Comfy 托管的签名 URL，自创建起最长 24 小时内有效。重放（replay）可能返回一个较早的 URL，而无法重新托管的素材会保留其有效期更短的提供商 URL。请及时下载 MP4，而不要只保存链接。当设置 draft: true 时，应读取 result.draft_cache，而不是期望获得 result.sample。

发布前须知

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