# FLUX 视频生成
> 文生视频、关键帧、视频续写
> 关键帧最多 10 张，按顺序均匀铺开
> 支持低清草稿预览再转正式渲染
`POST /v1/videos`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含视频本身。拿成片用 `task_id` 轮询[获取任务状态](../tasks/status.html)，成片地址在 `result.videos[0].url`，该地址约 24 小时后过期，请及时转存。
- `model` (string / 必填) — 取值 `flux-3-video`。
- `prompt` (string / 条件必填) — 画面描述。使用 `draft_from_task_id` 时必须省略，否则会被拒绝。
- `duration` (integer / 可选) — 时长，5 到 20 秒，默认 `5`。 传 `auto`、缺失或非整数都会静默回落为 5，`21` 会被拒绝。
- `resolution` (string / 可选) — 取值 `hd`、`fhd`，默认 `hd`。 `hd` 约 1280×704（16:9），`fhd` 约 1920×1088。草稿模式只支持 `hd`。
- `aspect_ratio` (string / 可选) — 取值 `21:9`、`2:1`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`auto`，默认 `auto`。
- `image_urls` (string[] / 可选) — 关键帧，1 到 10 张，公网地址或 Base64。 顺序有意义，不要排序或去重。1 张是首帧，2 张是首尾帧，3 到 10 张时首尾固定，中间帧均匀分布。
- `video_url` (string / 可选) — 续写的源视频，URL 或 Base64，格式 mp4。
- `video_urls` (string[] / 可选) — `video_url` 的别名，只取第一项。
- `audio` (boolean / 可选) — 是否生成音轨，默认 `true`。传 `false` 输出无声视频，价格不变。
- `draft` (boolean / 可选) — 生成低清草稿，价格约为正式渲染的三分之一，默认 `false`。强制 `hd`。
- `draft_from_task_id` (string / 可选) — 基于本人已完成的草稿任务转正式渲染。 除 `resolution` 外，其他参数沿用草稿，不能修改。
- `safety_tolerance` (integer / 可选) — 内容宽松度，0 到 4，默认 `2`，数值越大越宽松。
- `mode` (string / 可选) — 显式指定模式，取值 `t2v`、`i2v`、`v2v`、`draft_enhance`，也接受 `text-to-video`、`image-continuation`、`video-continuation`。 显式值优先于自动推断。
- `nsfw_check` (boolean / 可选) — 为 `true` 时先做内容审查，默认 `false`。
## 模式判定
省略 `mode` 时按输入推断，显式传 `mode` 时以显式值为准。
1. 只有 `prompt` —— 文生视频
2. 带 `image_urls` —— 关键帧控制
3. 带 `video_url` 或 `video_urls` —— 视频续写，单价更高
4. 图片与视频同时存在 —— 按续写处理
草稿分两步：先用 `draft: true` 出低清预览，再用 `draft_from_task_id` 转正式渲染。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `flux-3-video` | 当前唯一版本，支持文生、关键帧、续写与两段式草稿 |
## 使用限制
- 续写输出可能短于请求时长，例如请求 5 秒实际输出 4 秒；提交时按请求秒数预扣，完成后退回差额
- `draft: true` 与 `fhd` 不能同时出现
- `draft` 与 `draft_from_task_id` 不能同时出现
- 参数冲突返回 422
## 响应
提交成功返回统一的受理结构：
```json
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
- `code` (integer / 总是返回) — 状态码，`200` 表示任务已受理。
- `data` (array / 总是返回) — 本次提交的任务列表，逐项提交时按顺序排列。
- `data[].status` (string / 总是返回) — 受理状态，提交成功时为 `submitted`。
- `data[].task_id` (string / 总是返回) — 任务 ID，用它轮询结果。
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
取值冲突或非法时返回 422，同样不计费。
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 查询任务
`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` 给出原因。
**文生视频{Text to video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-video",
  "prompt": "沙漠中的公路，热浪扭曲空气，镜头低角度前进",
  "duration": 8,
  "resolution": "fhd",
  "aspect_ratio": "21:9"
}'
```
**文生视频{Text to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-video",
  "prompt": "沙漠中的公路，热浪扭曲空气，镜头低角度前进",
  "duration": 8,
  "resolution": "fhd",
  "aspect_ratio": "21:9"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生视频{Text to video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-video",
  "prompt": "沙漠中的公路，热浪扭曲空气，镜头低角度前进",
  "duration": 8,
  "resolution": "fhd",
  "aspect_ratio": "21:9"
}),
});
console.log(await res.json());
```
**200 文生视频{Text to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**关键帧{Keyframes}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-video",
  "prompt": "云层从晴空堆积成暴雨",
  "image_urls": [
    "https://example.com/clear.jpg",
    "https://example.com/storm.jpg"
  ],
  "duration": 8,
  "resolution": "fhd"
}'
```
**关键帧{Keyframes}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-video",
  "prompt": "云层从晴空堆积成暴雨",
  "image_urls": [
    "https://example.com/clear.jpg",
    "https://example.com/storm.jpg"
  ],
  "duration": 8,
  "resolution": "fhd"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**关键帧{Keyframes}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-video",
  "prompt": "云层从晴空堆积成暴雨",
  "image_urls": [
    "https://example.com/clear.jpg",
    "https://example.com/storm.jpg"
  ],
  "duration": 8,
  "resolution": "fhd"
}),
});
console.log(await res.json());
```
**200 关键帧{Keyframes}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**视频续写{Continue video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-video",
  "prompt": "镜头继续沿公路向前",
  "video_url": "https://example.com/clip.mp4",
  "duration": 8
}'
```
**视频续写{Continue video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-video",
  "prompt": "镜头继续沿公路向前",
  "video_url": "https://example.com/clip.mp4",
  "duration": 8
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**视频续写{Continue video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-video",
  "prompt": "镜头继续沿公路向前",
  "video_url": "https://example.com/clip.mp4",
  "duration": 8
}),
});
console.log(await res.json());
```
**200 视频续写{Continue video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**草稿预览{Draft preview}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-video",
  "prompt": "森林中的清晨光线，镜头缓慢升起",
  "duration": 8,
  "draft": true
}'
```
**草稿预览{Draft preview}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-video",
  "prompt": "森林中的清晨光线，镜头缓慢升起",
  "duration": 8,
  "draft": true
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**草稿预览{Draft preview}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-video",
  "prompt": "森林中的清晨光线，镜头缓慢升起",
  "duration": 8,
  "draft": true
}),
});
console.log(await res.json());
```
**200 草稿预览{Draft preview}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```