# PixVerse 视频生成
> 文生视频、图生视频、首尾帧、多图融合、视频延长
> 画幅支持最全，含 21:9 超宽
> 可一次性输出多段连续片段
`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 / 必填) — 取值 `pixverse-v6` 或 `pixverse-v6-max`。
- `prompt` (string / 必填) — 画面描述，所有模式都必填。上限 5000 字符。
- `negative_prompt` (string / 可选) — 反向描述，上限 2048 字符。
- `resolution` (string / 可选) — 输出分辨率，取值 `360p`、`540p`、`720p`、`1080p`，默认 `540p`。直接影响计费。
- `duration` (integer / 可选) — 时长，单位秒，默认 `5`。 通用范围 1 到 15；首尾帧模式只接受 `5` 或 `8`。
- `size` (string / 可选) — 输出画幅，取值 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`2:3`、`3:2`、`21:9`，默认 `16:9`。 只在文生视频与多图融合下生效。
- `image_urls` (string[] / 可选) — 图生视频的图片，只取第一张。
- `first_frame_image` (string / 可选) — 首帧，必须与 `last_frame_image` 成对使用。
- `last_frame_image` (string / 可选) — 尾帧，必须与 `first_frame_image` 成对使用。
- `img_references` (string[] / 可选) — 参考图，1 到 7 张。传入即进入多图融合模式。
- `extend_from_task_id` (string / 可选) — 要延长的任务 ID，必须是本人所有且状态为 `completed` 的 `pixverse-v6` 任务。
- `audio` (boolean / 可选) — 是否生成音轨，默认 `false`。开启会提高单价。
- `watermark` (boolean / 可选) — 是否在右下角加水印，默认 `false`。
- `motion_mode` (string / 可选) — 运动模式，只接受 `normal`。`fast` 属于旧模型，v6 会拒绝。
- `generate_multi_clip_switch` (boolean / 可选) — 输出多段连续片段，默认 `false`。仅文生视频与图生视频可用。
- `seed` (integer / 可选) — 随机种子，取值 0 到 2147483647，默认 `0`。
## 模式判定
按固定优先级判定，命中即停：
1. 没有任何图片或延长字段 —— 文生视频
2. 传了 `image_urls` —— 图生视频，只取第一张
3. 同时传 `first_frame_image` 与 `last_frame_image` —— 首尾帧过渡
4. 传了 `img_references` —— 多图融合
5. 传了 `extend_from_task_id` —— 视频延长
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `pixverse-v6` | 标准版，支持全部五种模式 |
| `pixverse-v6-max` | 画质更高的版本，参数与 v6 一致 |
## 使用限制
- 所有图片必须是公网可达的 HTTP(S) 地址，不接受 Base64 与 data URI
- 首尾帧只能选 5 秒或 8 秒
- `motion_mode` 只接受 `normal`
- 延长任务的源任务必须是本人所有且已完成
## 响应
提交成功返回统一的受理结构：
```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 | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
余额不足时部分上游返回 403 `quota_not_enough`，响应体带上余额与所需金额。
更多状态码与重试建议见[错误码与限流](../../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": "pixverse-v6",
  "prompt": "赛博朋克城市街道，雨后霓虹倒影，镜头缓慢横移",
  "resolution": "720p",
  "duration": 5,
  "size": "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": "pixverse-v6",
  "prompt": "赛博朋克城市街道，雨后霓虹倒影，镜头缓慢横移",
  "resolution": "720p",
  "duration": 5,
  "size": "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": "pixverse-v6",
  "prompt": "赛博朋克城市街道，雨后霓虹倒影，镜头缓慢横移",
  "resolution": "720p",
  "duration": 5,
  "size": "21:9"
}),
});
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": "pixverse-v6",
  "prompt": "人物转头微笑，头发被风吹动",
  "image_urls": [
    "https://example.com/portrait.png"
  ],
  "resolution": "720p",
  "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": "pixverse-v6",
  "prompt": "人物转头微笑，头发被风吹动",
  "image_urls": [
    "https://example.com/portrait.png"
  ],
  "resolution": "720p",
  "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": "pixverse-v6",
  "prompt": "人物转头微笑，头发被风吹动",
  "image_urls": [
    "https://example.com/portrait.png"
  ],
  "resolution": "720p",
  "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": "pixverse-v6",
  "prompt": "花朵从含苞到盛放",
  "first_frame_image": "https://example.com/bud.png",
  "last_frame_image": "https://example.com/bloom.png",
  "resolution": "720p",
  "duration": 5
}'
```
**首尾帧{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": "pixverse-v6",
  "prompt": "花朵从含苞到盛放",
  "first_frame_image": "https://example.com/bud.png",
  "last_frame_image": "https://example.com/bloom.png",
  "resolution": "720p",
  "duration": 5
}
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": "pixverse-v6",
  "prompt": "花朵从含苞到盛放",
  "first_frame_image": "https://example.com/bud.png",
  "last_frame_image": "https://example.com/bloom.png",
  "resolution": "720p",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 首尾帧{First and last frame}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**多图融合{Multi-image fusion}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "pixverse-v6",
  "prompt": "把三张参考图的产品放在同一个展台上",
  "img_references": [
    "https://example.com/p1.png",
    "https://example.com/p2.png",
    "https://example.com/p3.png"
  ],
  "resolution": "720p",
  "duration": 5
}'
```
**多图融合{Multi-image fusion}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "pixverse-v6",
  "prompt": "把三张参考图的产品放在同一个展台上",
  "img_references": [
    "https://example.com/p1.png",
    "https://example.com/p2.png",
    "https://example.com/p3.png"
  ],
  "resolution": "720p",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多图融合{Multi-image fusion}::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": "pixverse-v6",
  "prompt": "把三张参考图的产品放在同一个展台上",
  "img_references": [
    "https://example.com/p1.png",
    "https://example.com/p2.png",
    "https://example.com/p3.png"
  ],
  "resolution": "720p",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 多图融合{Multi-image fusion}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**视频延长{Extend 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": "pixverse-v6",
  "prompt": "镜头继续向后拉远",
  "extend_from_task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
  "resolution": "720p",
  "duration": 5
}'
```
**视频延长{Extend video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "pixverse-v6",
  "prompt": "镜头继续向后拉远",
  "extend_from_task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
  "resolution": "720p",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**视频延长{Extend 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": "pixverse-v6",
  "prompt": "镜头继续向后拉远",
  "extend_from_task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
  "resolution": "720p",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 视频延长{Extend video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```