创建 Veo 视频

POST/v1/videos
使用支持的 Veo 或 Gemini Omni 模型创建异步文生视频、单图驱动、首尾帧、多图参考或参考视频任务。请保存返回的公开任务 ID，并轮询查询接口直至任务完成。

异步调用流程

创建接口成功只表示任务已进入生成队列，并不表示视频已经生成完成。

  • 调用 POST /v1/videos，并保存响应中的 id。
  • 每 5～10 秒调用一次 GET /v1/videos/{task_id}，不要高频轮询。
  • status 变为 completed 后，从 url 下载或播放视频。
  • status 变为 failed 时查看 error。根据上游公开规则，上游生成失败的任务不扣费。

模型支持规格

模型 / 模式时长宽高比参考图参考视频分辨率
veo-3.1-fast-generate-preview4 / 6 / 8 秒16:9、9:160～2 张；1 张单图驱动，2 张首尾帧不支持720p
veo-3.1-generate-preview4 / 6 / 8 秒16:9、9:160～2 张；1 张单图驱动，2 张首尾帧不支持720p
veo-3.1-generate-preview-ref（带图）仅 8 秒仅 16:91～3 张多参考图不支持720p
veo-3.1-generate-preview-ref（不带图）4 / 6 / 8 秒16:9、9:16无不支持720p
gemini-omni-flash3～10 秒，每个整数均可16:9、9:160～1 张0～1 个公网地址，<=100 MiB720p

参考素材规则

  • 不传 image_url、image_urls 或 video_url 时为文生视频。
  • Fast 与标准 Veo：1 张图片表示单图驱动；2 张 image_urls 依次表示首帧、尾帧。
  • Ref 模型使用 image_urls 传 1～3 张多参考图；带图时必须使用 duration=8 和 aspect_ratio=16:9。
  • Gemini Omni 最多使用 1 张参考图或 1 个公网参考视频地址；参考视频必须可直接下载且不超过 100 MiB。
  • image_url 和 image_urls 不能同时传。图片支持公网 HTTP(S) 地址、data URL 或裸 base64，不接受 {data, mime_type} 对象。

提示词与可选控制

  • 不要在 prompt 中写时长和比例要求，请只使用 duration 和 aspect_ratio。
  • generate_audio 默认 true，传 false 可生成无声视频。
  • negative_prompt 用于描述不希望出现的画面内容。
  • 兼容 generateAudio 和 negativePrompt，但新接入建议使用 snake_case 字段。

Header 参数

Authorization:必填string

使用 Bearer 方案携带 API Key 的认证请求头。

示例Bearer <YOUR_API_KEY>
Content-Type:必填string

请求体的媒体类型。

示例application/json

请求体

application/json
model:必填enum<string>

选择一个支持的模型。不要把时长、宽高比或分辨率拼接到模型名中；各模型允许的输入组合请查看上方规格表。

可选值veo-3.1-fast-generate-previewveo-3.1-generate-previewveo-3.1-generate-preview-refgemini-omni-flash
示例veo-3.1-fast-generate-preview
prompt:必填string

非空的视频内容与运动描述。不要在提示词中写“竖屏”“vertical”“16:9”或“8 秒”等时长和比例要求，请使用对应参数。

示例一艘纸船沿着雨后水洼航行，电影感画面
duration:必填integer

必填的视频时长，单位为秒。Veo 模型仅支持 4、6、8；gemini-omni-flash 支持 3～10 的每个整数。veo-3.1-generate-preview-ref 带参考图时必须为 8。

可选值345678910
示例4
seconds:可选string

duration 的兼容字段，应传 JSON 字符串，例如 "4"。同时提供时以 duration 为准；新接入建议使用 duration。

可选值345678910
示例4
aspect_ratio:可选enum<string>

输出视频宽高比，默认 16:9。除带参考图的 veo-3.1-generate-preview-ref 必须使用 16:9 外，其余模式支持 16:9 和 9:16。

可选值16:99:16
示例16:9
image_url:可选string

单张参考图。image_url 与 image_urls 只能使用一个。支持可直接访问的公网 HTTP(S) 地址、data:image/...;base64,... URL 或裸 base64；不支持 {data, mime_type} 对象。

示例https://example.com/first-frame.jpg
image_urls:可选array<string>

参考图数组。Fast 与标准 Veo 最多 2 张，传 2 张时依次为首帧、尾帧；Ref 模型支持 1～3 张多参考图；Gemini Omni 最多 1 张。每项支持公网地址、data URL 或裸 base64。

示例["https://example.com/first-frame.jpg", "https://example.com/last-frame.jpg"]
video_url:可选string<uri>

仅 gemini-omni-flash 支持。提供一个服务端可直接下载、大小不超过 100 MiB 的公网 HTTP(S) 视频地址；不支持 data URL 或裸 base64 视频。

示例https://example.com/reference.mp4
generate_audio:可选boolean

是否随视频生成音频，默认 true；显式传 false 可生成无声视频。也兼容 generateAudio。

可选值truefalse
示例true
negative_prompt:可选string

描述不希望出现在结果中的内容。也兼容 negativePrompt。

示例模糊、面部变形、字幕
generateAudio:可选boolean

generate_audio 的驼峰兼容写法，新接入建议使用 generate_audio。

可选值truefalse
示例true
negativePrompt:可选string

negative_prompt 的驼峰兼容写法，新接入建议使用 negative_prompt。

示例模糊、面部变形、字幕

响应

200

成功时返回 JSON 响应。完整示例显示在右侧代码面板中。