Veo 系列
- 文生视频、首尾帧、参考图生视频
- 时长固定 8 秒，分辨率最高 4K
- 同名带
-ext后缀的别名与主名完全等价
认证
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 小时后过期，请及时转存。
取值 veo3.1-fast、veo3.1-quality、veo3.1-lite。
veo3.1-fast-ext、veo3.1-quality-ext、veo3.1-lite-ext 是等价的别名，输出完全一致。
画面描述。
固定为 8，只接受 8。
取值 16:9 横屏、9:16 竖屏。
取值 frame 表示首尾帧、reference 表示参考图。
省略时按图片数量推断：2 张为 frame，3 张为 reference。veo3.1-quality 在参考模式下不接受该字段，veo3.1-lite 不允许传。
最多 3 张，单张不超过 10MB，格式 jpeg、jpg、png、webp，必须是公网可访问地址。
frame 模式下第一张是首帧、第二张是尾帧。veo3.1-lite 不支持。
取值 720p、1080p、4k，默认 720p。
输出 GIF，默认 false。不能与 1080p 或 4k 同时使用。
允许回落到官方通道，默认 false。veo3.1-lite 不支持。
为 true 时先用 omni-moderation-latest 审查提示词与输入图片，默认 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.
veo3.1-fast, veo3.1-quality, or veo3.1-lite.
veo3.1-fast-ext, veo3.1-quality-ext, and veo3.1-lite-ext are equivalent aliases with identical output.
The scene description.
Fixed at 8; only 8 is accepted.
16:9 for landscape or 9:16 for portrait.
frame for first and last frames, reference for reference images.
When omitted it's inferred from the image count: 2 images means frame, 3 means reference. veo3.1-quality doesn't accept this field in reference mode, and veo3.1-lite doesn't allow it at all.
Up to 3, each under 10MB, formats jpeg, jpg, png, webp, and must be publicly reachable addresses.
In frame mode the first image is the opening frame and the second the closing frame. veo3.1-lite doesn't support this.
720p, 1080p, or 4k, default 720p.
Output a GIF; defaults to false. Can't be combined with 1080p or 4k.
Allows falling back to the official channel; defaults to false. veo3.1-lite doesn't support this.
When true, screens the prompt and input images with omni-moderation-latest first; defaults to false.
模式判定
只传 prompt 是文生视频。
传 image_urls 走图生视频：2 张按首尾帧处理，3 张按参考图处理。也可以显式传 generation_type 指定，显式值优先。
veo3.1-quality 不支持参考图模式，veo3.1-lite 不支持任何图片输入。
Only prompt means text to video.
Passing image_urls means image to video: 2 images are treated as first and last frames, 3 as reference images. You can also set generation_type explicitly, and an explicit value wins.
veo3.1-quality doesn't support reference-image mode, and veo3.1-lite doesn't support any image input.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
veo3.1-quality | 画质优先，仅支持文生视频与首尾帧 |
veo3.1-fast | 速度与画质均衡，支持全部三种模式 |
veo3.1-lite | 轻量档，仅文生视频，成本最低 |
| Model ID | Positioning |
|---|---|
veo3.1-quality | Quality first; supports only text to video and first-and-last frames |
veo3.1-fast | Balanced speed and quality; supports all three modes |
veo3.1-lite | Lightweight tier, text to video only, lowest cost |
使用限制
- 时长固定 8 秒，其他值一律拒绝
- 输出链接约 24 小时后过期
- GIF 输出不能与 1080p 或 4k 组合
veo3.1-lite不接受generation_type、image_urls、official_fallback
- Duration is fixed at 8 seconds; any other value is rejected
- Output links expire after about 24 hours
- GIF output can't be combined with 1080p or 4k
veo3.1-litedoesn't acceptgeneration_type,image_urls, orofficial_fallback
响应
提交成功返回统一的受理结构：
{
"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 | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
| 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.
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.