flux-3-generate

FLUX 3 生成

通过异步 API 执行已准备好的计划，保留即将过期的文件，并验证 MP4。构建请求前，请阅读 FLUX 3 API 参考；如果本技能与其不一致，应以 API 参考为准。使用 BFL_API_KEY 中的密钥，通过 x-key 标头进行身份验证；检查变量是否存在，但不要打印其值，也绝不要将密钥放入提示词、日志或已保存的请求正文中。

请求格式

每个请求都要指定 mode（必填，字符串必须完全匹配），并包含对应的媒体字段：

mode	媒体字段	模型的操作
t2v	无	仅根据文本生成视频片段
i2v	keyframes（必填）	将图像逐像素地作为固定帧显示在画面中
v2v	start_video（必填）	从视频片段的最后几帧继续生成
draft_enhance	draft_cache（必填）	以完整画质重新生成缓存的草稿；不接受任何其他字段，包括 prompt

• 该架构严格校验：任何未知字段都会返回 422 并指出字段名（Extra inputs are not permitted）。缺少必填字段也会以同样方式返回 422。
• 生成模式的设置：aspect_ratio（auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16）、duration（整数 5-20 或 "auto"）、resolution（hd 或 fhd）、generate_audio（布尔值）、draft（布尔值）、version。
• 参数之间存在联动限制（例如，较高分辨率的视频输入可能会限制时长）：请查阅参考文档，不要假定各字段互不影响。
• 三个或更多不带时间戳的关键帧，以及所有 [seconds, image] 时间戳关键帧，都需要设置整数 duration。媒体可通过公开 URL 或内联 base64 传输；关键帧图像至少为 256x256。

运行任务

1. 仅提交一次。 将返回的任务 id 和 polling_url 与不含密钥的请求一并保存。
2. 每 6 秒轮询一次，直到任务进入终止状态；使用 x-key 标头并跟随重定向。复杂请求需要较长规划时间是正常现象，不代表任务卡住。API 状态字符串必须完全匹配。对于 Pending、Reasoning、Generating，请继续轮询。对于 Ready（成功），以及 Error、Request Moderated、Content Moderated 或 Task not found（失败），请停止轮询。这些终止状态之后都不会变为 Ready。
   • 提交时遇到 429 表示组织的并发上限已满，且未创建任务。无需轮询。等待有可用名额后，再提交相同的请求正文。
   • 轮询时遇到 429 表示任务已存在且不受影响。退避后继续轮询相同的 polling_url。绝不要重新提交，否则将产生第二次渲染费用。
   • 503：采用有限退避。
3. 立即下载。 已观察到的签名样例 URL 和草稿缓存 URL 会在结果就绪后约一小时过期。URL 中的 se= 查询参数是权威的过期时间。应读取该参数，而不要假定固定的有效期。视频输出位于 result.samples 中，该字段是一个列表。草稿包位于 result.draft_caches 中，该字段也是一个列表。单数形式的 result.draft_cache 只是该列表的第一个元素，并非完整集合。遍历这两个列表中的每个元素，并在进行其他操作之前下载全部文件，同时记录每个元素对应的本地路径和任务 ID。只读取单数键 result.draft_cache 的客户端会悄悄漏掉已付费的文件；签名 URL 过期后，这些文件将无法恢复。保存下载的文件，以及任务 ID 和状态。
4. 验证：容器可以解码；时长、分辨率和宽高比符合预期；音频仅在请求时存在。技术有效不代表创作审核通过；请交由负责该内容的专业人员进行人工审核。

草稿

概念尚未得到验证时，添加 draft: true：快速生成低步数预览并使用 draft_cache，成本远低于完整渲染。评估草稿时，关注事件是否清晰易懂、 构图和连续性；低清晰度是低步数的取舍，完整画质渲染时会解决。仅增强选定的缓存 （它会重放相同的生成过程，因此有多个缓存时应保留草稿与缓存之间的对应关系）。

两次运行之间只更改一个重要维度。若结构相似的尝试连续两次未成功，请返回创意技能，而不是不断堆叠形容词。

参考资料

• references/api-quick-reference.md