快速开始
在你的 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
- Wait for the result
- Queue and collect later
Schema
Input
string
默认值:"\"auto\""
输出宽高比:auto、21:9、2:1、16:9、4:3、1:1、3:4 或 9:16。auto 会让 BFL 根据提示词和任何参考素材自行选择。
boolean
默认值:"false"
草稿模式:生成一份快速预览,其结果中包含一个 draft_cache 下载 URL。将该包连同 mode draft_enhance 一起发回,即可渲染同一次生成的完整质量版本。
string
仅 draft_enhance 使用。来自先前草稿生成的加密草稿缓存包,形式为 base64 编码的已下载包,或仍然有效的 http(s) URL。原始输入已嵌入该包中。
integer | string
默认值:"\"auto\""
视频时长(秒),可为 5 到 20 之间的任意整数秒,或使用 auto 自动适配内容。Range:
5 to 20boolean
默认值:"true"
在生成视频的同时生成同步音频。
string | number | string[] | string[] | number | string[][]
仅 i2v 使用。将成为视频帧的图像,每张为 http(s) URL 或 base64,总共一到十张。接受单张图像、图像列表(一张用于开始视频,两张分别作为起始和结束,更多则均匀分布且需要设定时长),或按时间顺序排列的带时间戳的 [秒数, 图像] 对,例如 [[0, ”…”], [3.5, ”…”]]。每个对是包含两个元素的数组:先是秒数,然后是图像。
string
必填
生成模式:t2v(文生视频)、i2v(图像续写)、v2v(视频续写)或 draft_enhance(对先前草稿进行完整质量渲染)。也接受 text-to-video 这类完整拼写的别名。
string
描述视频的自由格式提示词。除 draft_enhance 外的所有模式均必填。
string
视频分辨率级别:hd,或 fhd(由视频放大器完成更高分辨率的结果)。t2v、i2v 和 v2v 默认为 hd,draft_enhance 默认为 fhd。具体尺寸会随宽高比变化。Possible values:
hd, fhdinteger
默认值:"2"
输入与输出有害内容审核的容差级别,0 为最严格。无论请求的容差级别如何,色情内容均限制为级别 3,仇恨内容均限制为级别 2;带条件媒体的请求限制为级别 2。Range:
0 to 4string
仅 v2v 使用。要续接的视频,为 http(s) URL 或 base64 MP4;生成的片段将从其最后几帧继续。
string
默认值:"\"latest\""
端点版本。latest 提供当前发布版本;带日期的可固定发布标签会在发布时添加。
GET /v2/models/bfl/flux-3-video/openapi.json 提供的 Schema,也就是在请求到达提供商之前 Router 用于校验调用的同一份文档。
Output
number
提供商报告的以积分计的成本,在任务变为 Ready 后填充。Format:
floatstring
必填
BFL 任务标识符。
number
BFL 报告的可选生成进度。Range:
0 to 1Format: floatobject
必填
已完成的生成结果。两个 URL 叶子字段中恰好会填充其中一个:默认模式下为
sample,draft: true 模式下为 draft_cache。number
提供商报告的任务成本。这是 BFL 的数值,而不是 Comfy 的收费。Format:
doublestring (uri)
由
draft: true 模式返回、用于替代 sample 的签名 URL,其重新托管到 Comfy 存储的方式与 sample 相同:通常是有效期最长 24 小时的 Comfy 托管 URL;若无法完成重新托管,则为 BFL 自身约两小时有效的交付 URL。Format: uristring (uri)
已生成 MP4 的签名 URL。Router 会把该资源重新托管到 Comfy 存储并重写此字段,因此它通常是有效期最长 24 小时的 Comfy 托管 URL(签发时签名 24 小时,之后从 23 小时的备忘录中重放,所以后续轮询可能返回仅剩一小时有效期的链接);若某个叶子字段无法完成重新托管,则会保留 BFL 自身约两小时有效的交付 URL。在
draft: true 模式下不存在。Format: uristring
必填
任务状态:Pending、Reasoning、Generating、Ready、Request Moderated、Content Moderated、Error 或 Task not found。比较时不区分大小写;Router 会原样转发 BFL 的拼写。
示例
输入
输出
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 在调用提供商之前就拒绝了输入。生成的资源请及时下载,因为结果链接会过期。
请求头
身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
使用 Router API
模型发现、校验错误、重试与计费。
限制
Router 目前不支持的功能,以及替代方案。