FLUX 系列
- 文生视频、关键帧、视频续写
- 关键帧最多 10 张，按顺序均匀铺开
- 支持低清草稿预览再转正式渲染
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
取值 flux-3-video。
画面描述。使用 draft_from_task_id 时必须省略，否则会被拒绝。
时长，5 到 20 秒，默认 5。
传 auto、缺失或非整数都会静默回落为 5，21 会被拒绝。
取值 hd、fhd，默认 hd。
hd 约 1280×704（16:9），fhd 约 1920×1088。草稿模式只支持 hd。
取值 21:9、2:1、16:9、4:3、1:1、3:4、9:16、auto，默认 auto。
关键帧，1 到 10 张，公网地址或 Base64。
顺序有意义，不要排序或去重。1 张是首帧，2 张是首尾帧，3 到 10 张时首尾固定，中间帧均匀分布。
续写的源视频，URL 或 Base64，格式 mp4。
video_url 的别名，只取第一项。
是否生成音轨，默认 true。传 false 输出无声视频，价格不变。
生成低清草稿，价格约为正式渲染的三分之一，默认 false。强制 hd。
基于本人已完成的草稿任务转正式渲染。
除 resolution 外，其他参数沿用草稿，不能修改。
内容宽松度，0 到 4，默认 2，数值越大越宽松。
显式指定模式，取值 t2v、i2v、v2v、draft_enhance，也接受 text-to-video、image-continuation、video-continuation。
显式值优先于自动推断。
为 true 时先做内容审查，默认 false。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
Always flux-3-video.
The scene description. Must be omitted when using draft_from_task_id, or the request is rejected.
Duration, 5 to 20 seconds, default 5.
Passing auto, omitting it, or passing a non-integer silently falls back to 5; 21 is rejected.
hd or fhd, default hd.
hd is about 1280×704 (16:9) and fhd about 1920×1088. Draft mode supports only hd.
21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16, or auto; default auto.
Keyframes, 1 to 10, public URLs or Base64.
The order matters; don't sort or deduplicate. With 1 it's the first frame, with 2 it's the first and last frames, and with 3 to 10 the ends are fixed and the middle frames are spread evenly.
The source video to continue, as a URL or Base64, mp4 format.
An alias for video_url; only the first item is used.
Whether to generate an audio track; defaults to true. false produces a silent video at the same price.
Generate a low-resolution draft at about one third the price of the final render; defaults to false. Forces hd.
Promotes one of your own completed draft tasks to a final render.
Apart from resolution, all parameters carry over from the draft and can't be changed.
Content leniency, 0 to 4, default 2; higher is more permissive.
Explicitly set the mode: t2v, i2v, v2v, draft_enhance, or the aliases text-to-video, image-continuation, video-continuation.
An explicit value overrides auto-inference.
When true, runs a content check first. Defaults to false.
模式判定
省略 mode 时按输入推断，显式传 mode 时以显式值为准。
- 只有
prompt—— 文生视频 - 带
image_urls—— 关键帧控制 - 带
video_url或video_urls—— 视频续写，单价更高 - 图片与视频同时存在 —— 按续写处理
草稿分两步：先用 draft: true 出低清预览，再用 draft_from_task_id 转正式渲染。
When mode is omitted it's inferred from the input; an explicit mode wins.
- Only
prompt— text to video - With
image_urls— keyframe control - With
video_urlorvideo_urls— video continuation, at a higher unit price - Both images and video — treated as continuation
A draft is two steps: first draft: true for a low-resolution preview, then draft_from_task_id to promote it to the final render.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
flux-3-video | 当前唯一版本，支持文生、关键帧、续写与两段式草稿 |
| Model ID | Positioning |
|---|---|
flux-3-video | Currently the only version; supports text to video, keyframes, continuation, and two-stage drafts |
使用限制
- 续写输出可能短于请求时长，例如请求 5 秒实际输出 4 秒；提交时按请求秒数预扣，完成后退回差额
draft: true与fhd不能同时出现draft与draft_from_task_id不能同时出现- 参数冲突返回 422
- Continuation output may be shorter than requested — e.g. requesting 5 s but outputting 4 s; the request's seconds are held upfront and the difference refunded on completion
draft: trueandfhdcan't appear togetherdraftanddraft_from_task_idcan't appear together- Conflicting parameters return a 422
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
取值冲突或非法时返回 422，同样不计费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
Conflicting or illegal values return a 422, also unbilled.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.