# Veo 视频生成
> 文生视频、首尾帧、参考图生视频
> 时长固定 8 秒，分辨率最高 4K
> 同名带 `-ext` 后缀的别名与主名完全等价
`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 / 必填) — 取值 `veo3.1-fast`、`veo3.1-quality`、`veo3.1-lite`。 `veo3.1-fast-ext`、`veo3.1-quality-ext`、`veo3.1-lite-ext` 是等价的别名，输出完全一致。
- `prompt` (string / 必填) — 画面描述。
- `duration` (integer / 可选) — 固定为 8，只接受 `8`。
- `aspect_ratio` (string / 可选) — 取值 `16:9` 横屏、`9:16` 竖屏。
- `generation_type` (string / 可选) — 取值 `frame` 表示首尾帧、`reference` 表示参考图。 省略时按图片数量推断：2 张为 `frame`，3 张为 `reference`。`veo3.1-quality` 在参考模式下不接受该字段，`veo3.1-lite` 不允许传。
- `image_urls` (string[] / 可选) — 最多 3 张，单张不超过 10MB，格式 jpeg、jpg、png、webp，必须是公网可访问地址。 `frame` 模式下第一张是首帧、第二张是尾帧。`veo3.1-lite` 不支持。
- `resolution` (string / 可选) — 取值 `720p`、`1080p`、`4k`，默认 `720p`。
- `enable_gif` (boolean / 可选) — 输出 GIF，默认 `false`。不能与 1080p 或 4k 同时使用。
- `official_fallback` (boolean / 可选) — 允许回落到官方通道，默认 `false`。`veo3.1-lite` 不支持。
- `nsfw_check` (boolean / 可选) — 为 `true` 时先用 `omni-moderation-latest` 审查提示词与输入图片，默认 `false`。
## 模式判定
只传 `prompt` 是文生视频。
传 `image_urls` 走图生视频：2 张按首尾帧处理，3 张按参考图处理。也可以显式传 `generation_type` 指定，显式值优先。
`veo3.1-quality` 不支持参考图模式，`veo3.1-lite` 不支持任何图片输入。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `veo3.1-quality` | 画质优先，仅支持文生视频与首尾帧 |
| `veo3.1-fast` | 速度与画质均衡，支持全部三种模式 |
| `veo3.1-lite` | 轻量档，仅文生视频，成本最低 |
## 使用限制
- 时长固定 8 秒，其他值一律拒绝
- 输出链接约 24 小时后过期
- GIF 输出不能与 1080p 或 4k 组合
- `veo3.1-lite` 不接受 `generation_type`、`image_urls`、`official_fallback`
## 响应
提交成功返回统一的受理结构：
```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": "veo3.1-fast",
  "prompt": "海边悬崖上的灯塔，海浪拍打礁石，黄昏光线",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}'
```
**文生视频{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": "veo3.1-fast",
  "prompt": "海边悬崖上的灯塔，海浪拍打礁石，黄昏光线",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}
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": "veo3.1-fast",
  "prompt": "海边悬崖上的灯塔，海浪拍打礁石，黄昏光线",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}),
});
console.log(await res.json());
```
**200 文生视频{Text 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": "veo3.1-fast",
  "prompt": "季节从春天过渡到冬天，树叶由绿转白",
  "generation_type": "frame",
  "image_urls": [
    "https://example.com/spring.jpg",
    "https://example.com/winter.jpg"
  ],
  "duration": 8
}'
```
**首尾帧{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": "veo3.1-fast",
  "prompt": "季节从春天过渡到冬天，树叶由绿转白",
  "generation_type": "frame",
  "image_urls": [
    "https://example.com/spring.jpg",
    "https://example.com/winter.jpg"
  ],
  "duration": 8
}
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": "veo3.1-fast",
  "prompt": "季节从春天过渡到冬天，树叶由绿转白",
  "generation_type": "frame",
  "image_urls": [
    "https://example.com/spring.jpg",
    "https://example.com/winter.jpg"
  ],
  "duration": 8
}),
});
console.log(await res.json());
```
**200 首尾帧{First and last frame}**
```
{
  "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": "veo3.1-fast",
  "prompt": "三个角色在同一个场景中并排站立，镜头缓慢环绕",
  "generation_type": "reference",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png",
    "https://example.com/c.png"
  ],
  "duration": 8
}'
```
**参考图生视频{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": "veo3.1-fast",
  "prompt": "三个角色在同一个场景中并排站立，镜头缓慢环绕",
  "generation_type": "reference",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png",
    "https://example.com/c.png"
  ],
  "duration": 8
}
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": "veo3.1-fast",
  "prompt": "三个角色在同一个场景中并排站立，镜头缓慢环绕",
  "generation_type": "reference",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png",
    "https://example.com/c.png"
  ],
  "duration": 8
}),
});
console.log(await res.json());
```
**200 参考图生视频{Reference to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**4K 输出{4K output}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "veo3.1-quality",
  "prompt": "雪山日出，云海翻涌，航拍缓慢推进",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "4k"
}'
```
**4K 输出{4K output}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "veo3.1-quality",
  "prompt": "雪山日出，云海翻涌，航拍缓慢推进",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "4k"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**4K 输出{4K output}::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": "veo3.1-quality",
  "prompt": "雪山日出，云海翻涌，航拍缓慢推进",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "4k"
}),
});
console.log(await res.json());
```
**200 4K 输出{4K output}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```