GuideTool IntegrationsAPI ReferenceTerms & Policies
zhAPI 接口文档视频系列模型Veo 3.1
API 接口文档

Veo 3.1

Veo 3.1 文生视频 / 图生视频，支持原生音频与首尾帧插值

Veo 3.1 生成 4–8 秒视频，可选原生同步音频，支持首帧、首尾帧插值与参考图三种工作流。

所有任务均为异步：提交后轮询任务状态，再下载结果。完整生命周期见「视频生成与查询」页。

模型一览

veo-3.1-generate-preview — 最高画质，原生音频，最高 4K。时长 4 / 6 / 8 秒；宽高比 16:9 / 9:16。

veo-3.1-fast-generate-preview — 画质与速度均衡。时长 4 / 6 / 8 秒；宽高比 16:9 / 9:16。

veo-3.1-lite-generate-preview — 速度最快、成本最低；不支持 4k。时长 4 / 6 / 8 秒；宽高比 16:9 / 9:16。

提交生成任务

openaiFailover: disabled

按请求体中的 model 字段路由到对应模型。

任务创建非幂等，视频路由禁用 failover 重试。

POST/v1/videos兼容别名POST/v1/video/generations

请求

字段

JSON 请求体。

modelstringRequired

Veo 3.1 模型 ID。

veo-3.1-generate-previewveo-3.1-fast-generate-previewveo-3.1-lite-generate-preview
promptstringOptional

视频描述提示词。文生视频时必填；通过 image、images、lastFrameImage 或 input_reference 提供图像输入时可选。中英文均可，英文通常效果最佳。

size / resolutionstringOptional

分辨率。4k 仅非 lite 模型支持。不传则使用模型默认值。

720p1080p4k
duration / secondsinteger | stringOptional

视频时长（秒）。1080p 或 4k 分辨率下仅支持 8 秒。

468
aspect_ratiostringOptional

宽高比，默认 16:9。

16:99:16
generate_audiobooleanOptional

是否生成同步音频。不显式设置则不开启——开启后费用约翻倍。

enhance_promptbooleanOptional

是否启用提示词增强。不显式设置则不开启。

negative_promptstringOptional

负向提示词，描述不希望出现的内容。

seedintegerOptional

随机种子，0 至 2^32 - 1。尽力复现，不保证确定性。

person_generationstringOptional

人物生成策略。

allow_allallow_adultdisallow
imagestringOptional

图生视频首帧图。支持 HTTP(S) URL、data URI 或纯 base64。

imagesarray<string>Optional

图片数组，取第一张作为主图输入。

lastFrameImagestringOptional

尾帧图。与 image 配合时在首尾帧之间插值生成。

input_referencestringOptional

参考图输入。支持 HTTP(S) URL、data URI 或纯 base64。

image_mime_typestringOptional

可选：所传图片的 MIME 类型提示，如 image/png。

响应

字段

提交回执。字段平铺在 JSON 顶层（无 data 包装）。

idstringOptional

任务 ID（task_xxx）。与 task_id 相同，供 OpenAI SDK 兼容使用。

task_idstringOptional

任务 ID，用于后续轮询与下载。

objectstringOptional

固定值 video。

modelstringOptional

请求中传入的模型名。

statusstringOptional

提交后初始状态，通常为 QUEUED。

SUBMITTEDQUEUEDIN_PROGRESSSUCCESSFAILURE
progressintegerOptional

进度 0–100，刚提交时通常为 0。

created_atintegerOptional

任务创建时间（秒级时间戳）。

4K 输出（resolution = 4k）仅非 lite 模型支持。

1080p 与 4k 分辨率仅支持 8 秒时长。

不显式设置 generate_audio 为 true 则不生成音频（开启后费用约翻倍）。

成功与业务失败均返回 HTTP 200。调用失败时响应体不含回执字段，而是携带 error 对象——{ "error": { "message", "type", "code" } }——请通过是否存在 error 字段区分。

查询与下载

轮询任务直到进入终态 SUCCESS 或 FAILURE（建议间隔 10–15 秒，不要低于 5 秒），然后下载结果。下载接口支持 Range 请求（HTTP 206），可断点续传、拖拽播放。

GET/v1/videos/{task_id}兼容别名GET/v1/video/generations/{task_id}
GET/v1/videos/{task_id}/content

响应

字段

以下为核心字段。完整的任务详情字段、状态生命周期与轮询建议见「视频生成与查询」页。

statusstringOptional

任务状态。

SUBMITTEDQUEUEDIN_PROGRESSSUCCESSFAILURE
progressstringOptional

进度百分比字符串，如 "50%"。

result_urlstringOptional

结果视频下载地址，仅 status 为 SUCCESS 时返回。形如 /v1/videos/{task_id}/content。

fail_reasonstringOptional

失败原因，仅 status 为 FAILURE 时返回。

相关页面

视频生成与查询HappyHorseSeedance