# Wan 视频生成
> 文生视频、图生视频、首尾帧、续写、参考生视频、视频编辑
> 支持自定义配乐与文档生视频
> 输出可带头部音轨
`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 / 必填) — 视频模型 ID，取值见下方模型列表。
- `prompt` (string / 条件必填) — 画面描述。文生视频必填；图生视频建议填写，用来控制镜头运动。 wan3.0 上限 20000 字符，超出部分自动截断；wan2.7 上限 5000 字符。
- `negative_prompt` (string / 可选) — 反向描述，写不希望出现的内容，如模糊、变形、低质量。上限 500 字符。
- `resolution` (string / 可选) — 输出分辨率，取值随模型变化： - `wan2.5-preview`：`480p`、`720p`、`1080p` - `wan2.6`：`720p`、`1080p` - `wan2.7`、`wan3.0-video`：`720P`、`1080P`，`wan3.0` 另有 `480P`
- `size` (string / 可选) — 输出画幅，取值 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`，`wan3.0` 还接受 `adaptive`。 只在文生视频生效，图生视频沿用输入图片比例。别名 `aspect_ratio`。
- `duration` (integer / 可选) — 时长，单位秒。 - `wan2.5-preview`：`5` 或 `10` - `wan2.6`：`5`、`10`、`15` - `wan2.7`：2 到 15 - `wan3.0-video`：2 到 30，或 `-1` 由模型自行决定
- `image_urls` (string[] / 可选) — 图生视频的图片，公网地址或 Base64 data URI。 1 张为首帧，2 张为首帧加尾帧。`wan3.0` 在参考模式下最多 10 张。
- `image_with_roles` (object[] / 可选) — 带角色的图片数组，每项含 `url` 与 `role`。 `role` 取值 `first_frame`、`last_frame`、`reference_image`。
- `video_urls` (string[] / 可选) — 续写或参考视频。wan2.7 只取第一段，时长 2 到 10 秒；wan3.0 最多 5 段，合计不超过 15 秒。
- `audio_url` (string / 可选) — 自定义音频。文生视频下作为背景音乐；图生视频下驱动画面节奏。 格式 wav 或 mp3，2 到 30 秒，不超过 15MB。
- `audio` (boolean / 可选) — 是否生成音轨。`wan2.5` 默认 `true` 且不支持关闭；`wan3.0` 默认 `true` 可关闭，开关不影响价格。
- `prompt_extend` (boolean / 可选) — 自动扩写提示词。短提示词收益明显，代价是生成时间变长。
- `seed` (integer / 可选) — 随机种子，取值 0 到 2147483647。相同种子趋向相似结果，但不保证完全一致。
- `generation_type` (string / 可选) — `wan3.0` 专用，取值 `frame` 或 `reference`，决定裸 `image_urls` 归入哪一族。
- `file_url` (string / 可选) — `wan3.0` 专用，文档生视频的输入文件。 docx、pdf、txt 等格式，不超过 100MB 或 50 页，不能与 `link_url` 同时使用。
- `link_url` (string / 可选) — `wan3.0` 专用，网页生视频的输入链接。必须公网可访问且无需登录。
- `watermark` (boolean / 可选) — 是否在右下角添加 AI 生成标识，默认 `false`。
## 模式判定
不带媒体字段是文生视频。
带 `image_urls` 或 `image_with_roles` 走图生视频：1 张首帧，2 张首尾帧，带 `reference_image` 角色或配合参考视频、音频、文档时转为参考生视频。
带 `video_urls` 是续写；带 `file_url` 或 `link_url` 是文档或网页生视频。
帧族（首帧、尾帧）与参考族（参考图、参考视频、参考音频、文档、链接）互斥，混用返回 400，不创建任务也不扣费。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `wan3.0-video` | 当前旗舰，支持文档生视频与 2 到 30 秒时长 |
| `wan3.0-video-prime` | 3.0 的高画质版，参数与 `wan3.0-video` 完全一致 |
| `wan2.7` | 文生、图生、续写三合一 |
| `wan2.6` | 支持镜头类型与 13 种趣味模板 |
| `wan2.5-preview` | 支持音轨自动生成与自定义配乐 |
## 使用限制
- 帧族与参考族不能混用
- `file_url` 与 `link_url` 不能同时传
- 有视频输入时，输入总时长加输出时长不超过 30 秒
- 参考图最多 10 张
- 参数错误同步返回 400，不扣费
## 响应
提交成功返回统一的受理结构：
```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 | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
更多状态码与重试建议见[错误码与限流](../../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": "wan3.0-video",
  "prompt": "夕阳下的海边公路，慢镜头推进，电影感画面",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "audio": true
}'
```
**文生视频{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": "wan3.0-video",
  "prompt": "夕阳下的海边公路，慢镜头推进，电影感画面",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "audio": true
}
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": "wan3.0-video",
  "prompt": "夕阳下的海边公路，慢镜头推进，电影感画面",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "audio": true
}),
});
console.log(await res.json());
```
**200 文生视频{Text to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**图生视频{Image 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": "wan3.0-video",
  "prompt": "人物缓缓站起身，向镜头走来",
  "image_urls": [
    "https://example.com/person.jpg"
  ],
  "resolution": "1080P",
  "duration": 5
}'
```
**图生视频{Image to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan3.0-video",
  "prompt": "人物缓缓站起身，向镜头走来",
  "image_urls": [
    "https://example.com/person.jpg"
  ],
  "resolution": "1080P",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**图生视频{Image 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": "wan3.0-video",
  "prompt": "人物缓缓站起身，向镜头走来",
  "image_urls": [
    "https://example.com/person.jpg"
  ],
  "resolution": "1080P",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 图生视频{Image to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**首尾帧{First and last frame}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "镜头从海边缓慢移向山顶",
  "image_urls": [
    "https://example.com/beach.jpg",
    "https://example.com/mountain.jpg"
  ],
  "resolution": "1080P",
  "duration": 10
}'
```
**首尾帧{First and last frame}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan3.0-video",
  "prompt": "镜头从海边缓慢移向山顶",
  "image_urls": [
    "https://example.com/beach.jpg",
    "https://example.com/mountain.jpg"
  ],
  "resolution": "1080P",
  "duration": 10
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**首尾帧{First and last frame}::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": "wan3.0-video",
  "prompt": "镜头从海边缓慢移向山顶",
  "image_urls": [
    "https://example.com/beach.jpg",
    "https://example.com/mountain.jpg"
  ],
  "resolution": "1080P",
  "duration": 10
}),
});
console.log(await res.json());
```
**200 首尾帧{First and last frame}**
```
{
  "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": "wan3.0-video",
  "prompt": "继续向前走，镜头跟随",
  "video_urls": [
    "https://example.com/clip.mp4"
  ],
  "resolution": "1080P",
  "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": "wan3.0-video",
  "prompt": "继续向前走，镜头跟随",
  "video_urls": [
    "https://example.com/clip.mp4"
  ],
  "resolution": "1080P",
  "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": "wan3.0-video",
  "prompt": "继续向前走，镜头跟随",
  "video_urls": [
    "https://example.com/clip.mp4"
  ],
  "resolution": "1080P",
  "duration": 8
}),
});
console.log(await res.json());
```
**200 续写视频{Continue video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**参考生视频{Reference 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": "wan3.0-video",
  "prompt": "图1 中的人物走进 视频1 的街道场景",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "generation_type": "reference",
  "duration": 5
}'
```
**参考生视频{Reference to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan3.0-video",
  "prompt": "图1 中的人物走进 视频1 的街道场景",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "generation_type": "reference",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**参考生视频{Reference 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": "wan3.0-video",
  "prompt": "图1 中的人物走进 视频1 的街道场景",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "generation_type": "reference",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 参考生视频{Reference to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**文档生视频{Document 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": "wan3.0-video",
  "file_url": "https://example.com/brief.pdf",
  "resolution": "1080P",
  "duration": 10
}'
```
**文档生视频{Document to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan3.0-video",
  "file_url": "https://example.com/brief.pdf",
  "resolution": "1080P",
  "duration": 10
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文档生视频{Document 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": "wan3.0-video",
  "file_url": "https://example.com/brief.pdf",
  "resolution": "1080P",
  "duration": 10
}),
});
console.log(await res.json());
```
**200 文档生视频{Document to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```