flux-3-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FLUX 3 Generate

FLUX 3 生成功能

Execute a ready plan through the asynchronous API, preserve expiring artifacts, and verify the MP4. Read the FLUX 3 API reference before building a request; it is authoritative wherever this skill disagrees. Authenticate with the

x-key

header from

BFL_API_KEY

; check the variable exists without printing it, and never put keys in prompts, logs, or saved request bodies.

通过异步API执行已准备好的方案，保留即将过期的工件，并验证MP4文件。在构建请求前，请阅读FLUX 3 API参考文档；当本技能与参考文档存在分歧时，以参考文档为准。使用

BFL_API_KEY

中的

x-key

请求头进行身份验证；请检查该变量是否存在，但不要打印它，绝对不要将密钥放入提示词、日志或保存的请求体中。

Request shape

请求格式

Every request names its

mode

(required, exact strings) and carries the matching media field:

`mode`	Media field	What the model does
`t2v`	none	Generates the clip from your text alone
`i2v`	`keyframes` (required)	Puts your images on screen, pixel for pixel, as pinned frames
`v2v`	`start_video` (required)	Continues from the final frames of your clip
`draft_enhance`	`draft_cache` (required)	Replays a cached draft at full quality; accepts no other fields, not even `prompt`

The schema is strict: any field it does not know returns a
```
422
```
naming it (
```
Extra inputs are not permitted
```
). A missing required field 422s the same way.

Settings on the generating modes:

aspect_ratio

(

auto

21:9

2:1

16:9

4:3

1:1

3:4

9:16

duration

(integer 5-20 or

"auto"

resolution

(

hd

fhd

generate_audio

(bool),

draft

(bool),

version

Constraints couple (a video input at higher resolution may cap duration): read the reference rather than assuming fields are independent.
Three or more bare keyframes, and all
```
[seconds, image]
```
timestamped keyframes, need an integer
```
duration
```
. Media travels as a public URL or inline base64; keyframe images are at least 256x256.

每个请求都需要指定

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。

Run a job

运行任务

Submit once. Persist the returned task
```
id
```
and
```
polling_url
```
with the secret-free request.
Poll every 6 seconds to a terminal state with the
```
x-key
```
header, following redirects. Planning time on a complex brief is normal, not a stall. The API status strings are exact. KEEP POLLING on
```
Pending
```
,
```
Reasoning
```
,
```
Generating
```
. STOP on
```
Ready
```
(success) and on
```
Error
```
,
```
Request Moderated
```
,
```
Content Moderated
```
, or
```
Task not found
```
(failures). None of these terminal statuses ever later becomes
```
Ready
```
.
- ```
429
```
  on submit means your org's concurrency ceiling is full and no task was created. There is nothing to poll. Wait for a slot, then resubmit the same body.
- ```
429
```
  on poll means the task exists and is unaffected. Back off and keep polling the same
```
polling_url
```
  . Never resubmit, or you pay for a second render.
- ```
503
```
  : bounded backoff.
Download immediately. Observed signed sample and draft cache URLs expire roughly one hour after the result is ready. The
```
se=
```
query parameter on the URL itself is the authoritative expiry. Read it rather than assuming a fixed window. Video outputs arrive in
```
result.samples
```
, which is a list. Draft bundles arrive in
```
result.draft_caches
```
, which is also a list. The singular
```
result.draft_cache
```
is the first element of that list, not the complete set. Iterate every element of both lists and download all of them before doing anything else, recording the local path and task ID per element. A client reading only the singular
```
result.draft_cache
```
key silently drops paid artifacts that cannot be recovered once the signed URLs expire. Save the downloaded files, plus task ID and status.
Validate: container decodes, duration/resolution/aspect match intent, audio present exactly when requested. Technical validity is not creative approval; hand review to the specialist that owns it.

仅提交一次。将返回的任务
```
id
```
和
```
polling_url
```
与不含密钥的请求内容一起保存。
每6秒轮询一次，携带
```
x-key
```
请求头，直到任务进入终端状态，期间需跟随重定向。复杂需求的方案规划时间属于正常情况，并非卡顿。API返回的状态字符串是精确的。当状态为
```
Pending
```
、
```
Reasoning
```
、
```
Generating
```
时，持续轮询。当状态为
```
Ready
```
（成功）或
```
Error
```
、
```
Request Moderated
```
、
```
Content Moderated
```
、
```
Task not found
```
（失败）时，停止轮询。这些终端状态永远不会再变为
```
Ready
```
。
- 提交时返回
```
429
```
  错误表示你的组织并发上限已达，未创建任何任务，无需轮询。等待空闲名额后，重新提交相同的请求体。
- 轮询时返回
```
429
```
  错误表示任务已存在且未受影响。请延长轮询间隔并继续使用相同的
```
polling_url
```
  轮询，绝对不要重新提交，否则会为第二次渲染付费。
- 返回
```
503
```
  错误：请进行有限次数的退避重试。
立即下载。已观测到签名的样本和草稿缓存URL会在结果就绪后约1小时过期。URL中的
```
se=
```
查询参数是权威的过期标识，请以此为准，不要假设固定的过期窗口。视频输出位于
```
result.samples
```
（数组类型）。草稿包位于
```
result.draft_caches
```
（同样为数组类型）。单数形式的
```
result.draft_cache
```
是该数组的第一个元素，而非完整集合。请遍历两个数组的所有元素并优先下载全部内容，记录每个元素的本地路径和任务ID。若客户端仅读取单数形式的
```
result.draft_cache
```
字段，会静默丢失付费生成的工件，且一旦签名URL过期便无法恢复。请保存下载的文件，以及任务ID和状态。
验证：容器可解码、时长/分辨率/宽高比符合预期、音频完全按要求存在。技术验证不等于创意审核，需交由专业人员进行人工审核。

Drafts

草稿功能

Add

draft: true

while a concept is unproven: a fast low-step preview plus a

draft_cache

costs far less than a full render. Judge a draft on event legibility, composition, and continuity; softness is the low-step trade and resolves at full quality. Enhance only the chosen cache (it replays the same generation, so preserve draft-to-cache identity when several are in play).

Between reruns change one consequential dimension. After two structurally similar misses, return to the creative skill instead of accumulating adjectives.

当概念尚未确定时，添加

draft: true

参数：快速生成的低步数预览加上

draft_cache

的成本远低于完整渲染。判断草稿时需关注事件清晰度、构图和连续性；模糊是低步数的代价，在全质量渲染时会消失。仅对选定的缓存进行增强（增强会重放相同的生成过程，因此当存在多个草稿时，请保留草稿与缓存的对应关系）。

多次重试时，请仅修改一个关键维度。若两次结构相似的尝试均未达到预期，请回到创意技能环节，不要堆砌修饰词。

References

参考资料

references/api-quick-reference.md

references/api-quick-reference.md