Veo 模型图生视频接口文档¶

Veo 是 Google 开发的高质量图像到视频生成模型，本文档描述了使用 Google Veo 模型进行图像到视频生成的完整 API 接口规范。所有视频生成调用都使用相同的 /v1/video/generations 端点，根据用例使用不同的参数。图像数据以 base64 编码字符串的形式提供。

概述¶

Veo 模型图生视频功能提供异步任务处理机制：

提交任务：发送图像和文本提示词，创建视频生成任务
查询状态：通过任务 ID 查询生成进度和状态
获取结果：任务完成后获取生成的视频文件

任务状态流转¶

queued → in_progress → completed
                ↓
            failed

queued: 任务已提交，等待处理
in_progress: 任务正在处理中
completed: 任务成功完成，视频已生成
failed: 任务失败

接口列表¶

方法	路径	说明
POST	/v1/video/generations	提交视频生成任务（标准格式）
GET	/v1/video/generations/{task_id}	查询任务状态（标准格式）
POST	/v1/videos	提交视频生成任务
GET	/v1/videos/{task_id}	查询任务状态
GET	/v1/videos/{task_id}/content	获取视频内容（流式下载）

调用示例¶

1. 基础图生视频¶

最简单的图生视频形式使用单个图像作为第一帧。

请求体：

{
  "model": "veo-3.0-fast-generate-001",
  "prompt": "A cat playing piano in a beautiful garden",
  "image": "<BASE64_ENCODED_IMAGE_DATA>",
  "metadata": {}
}

2. 首帧和末帧¶

image 字段中的图像指定视频的第一帧。metadata.lastFrame 中的图像指定最后一帧。这允许您控制生成视频的起始帧和结束帧。

注意： 此功能仅由 Veo 3.1 模型支持。

请求体：

{
  "model": "veo-3.0-fast-generate-001",
  "prompt": "A cat playing piano in a beautiful garden",
  "image": "<BASE64_ENCODED_IMAGE_DATA>",
  "metadata": {
    "lastFrame": "<BASE64_ENCODED_IMAGE_DATA>"
  }
}

3. 参考图像¶

图像在 metadata.referenceImages 中的数组里指定，最多包含 3 个元素。每个参考图像是一个对象，包含 image：base64 编码的图像数据和 referenceType：值为 "asset" 或 "style" 的字符串。

注意： 此功能仅由 veo-3.1-generate-preview 支持。

请求体：

{
  "model": "veo-3.0-fast-generate-001",
  "prompt": "A cat playing piano in a beautiful garden",
  "image": "<BASE64_ENCODED_IMAGE_DATA>",
  "metadata": {
    "referenceImages": [
      {
        "image": "<BASE64_ENCODED_IMAGE_DATA>",
        "referenceType": "asset"
      },
      {
        "image": "<BASE64_ENCODED_IMAGE_DATA>",
        "referenceType": "style"
      }
    ]
  }
}

请求参数说明:¶

参数	类型	必填	说明
model	string	是	模型名称，如 veo-3.0-fast-generate-001
prompt	string	是	文本提示词，描述要生成的视频内容
image	string	是	第一帧的 base64 编码图像数据
metadata	object	否	扩展参数对象

metadata 参数说明:¶

参数	类型	必填	说明
aspectRatio	string	否	视频宽高比，可选值："16:9"、"9:16"
durationSeconds	number	否	视频时长（秒），可选值：4、6、8
negativePrompt	string	否	负面提示词，描述不希望在视频中出现的内容
personGeneration	string	否	人物生成策略，可选值："allow_all"（文生视频）、"allow_adult"（图生视频）
resolution	string	否	视频分辨率，如 "1080p"、"720p"
sampleCount	number	否	生成视频数量，默认 1
storageUri	string	否	Google Cloud Storage URI，用于存储生成的视频
lastFrame	string	否	最后一帧的 base64 编码图像数据（仅 Veo 3.1 模型）
referenceImages	array	否	参考图像数组，最多 3 个元素（仅 veo-3.1-generate-preview）

referenceImages 数组元素说明:¶

参数	类型	必填	说明
image	string	是	Base64 编码的图像数据
referenceType	string	是	参考类型，可选值："asset" 或 "style"

1. 提交视频生成任务¶

完整请求：¶

curl -X POST "https://computevault.unodetech.xyz/v1/video/generations" -H "Content-Type: application/json" -H "Authorization: Bearer API_KEY" -d @veoImageToVideoTest.json

接口地址:¶

POST /v1/video/generations

请求头:¶

参数	类型	必填	描述
Content-Type	string	是	application/json
Authorization	string	是	Bearer API_KEY

响应示例:¶

{
  "task_id": "TASK_ID"
}

响应字段说明:¶

字段	类型	说明
task_id	string	任务 ID，用于后续查询任务状态

2. 查询任务状态¶

完整标准格式接口¶

curl -X GET "https://computevault.unodetech.xyz/v1/video/generations/TASK_ID" -H "Authorization: Bearer API_KEY"

接口地址:¶

GET /v1/video/generations/{task_id}

请求头:¶

参数	类型	必填	描述
Authorization	string	是	Bearer API_KEY

路径参数:¶

参数	类型	必填	说明
task_id	string	是	任务 ID

响应示例（处理中）:¶

{
  "code": "success",
  "message": "",
  "data": {
    "bytes_base64_encoded": "",
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "processing",
    "task_id": "TASK_ID",
    "url": ""
  }
}

响应示例（成功）:¶

{
  "code": "success",
  "message": "",
  "data": {
    "bytes_base64_encoded": "",
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "TASK_ID",
    "url": "https://computevault.unodetech.xyz/v1/videos/TASK_ID/content"
  }
}

注意： 根据 AI 服务提供商的不同，视频将以 bytes_base64_encoded 字段中的 base64 编码数据（Vertex）或 url 字段中的内容 URL（Gemini）的形式返回。

响应示例（失败）:¶

{
  "code": "success",
  "message": "",
  "data": {
    "bytes_base64_encoded": "",
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "failed",
    "task_id": "TASK_ID",
    "url": "Reference to video does not support this mix of reference images."
  }
}

当任务失败时，url 字段包含错误消息而不是视频 URL。

响应字段说明:¶

字段	类型	说明
code	string	响应状态码，"success" 表示成功
data	object	任务数据对象
data.task_id	string	任务 ID
data.status	string	任务状态：queued、in_progress、succeeded、failed
data.format	string	视频格式，如 "mp4"
data.url	string	视频访问 URL（任务成功时），或错误消息（任务失败时）
data.bytes_base64_encoded	string	Base64 编码的视频数据（可用时）
data.error	object	错误信息（任务失败时）
message	string	错误消息

Veo 模型图生视频接口文档¶

概述¶

任务状态流转¶

接口列表¶

调用示例¶

1. 基础图生视频¶

2. 首帧和末帧¶

3. 参考图像¶

请求参数说明:¶

metadata 参数说明:¶

referenceImages 数组元素说明:¶

1. 提交视频生成任务¶

完整请求：¶

接口地址:¶

请求头:¶

响应示例:¶

响应字段说明:¶

2. 查询任务状态¶

完整标准格式接口¶

接口地址:¶

请求头:¶

路径参数:¶

响应示例（处理中）:¶

响应示例（成功）:¶

响应示例（失败）:¶

响应字段说明:¶

相关链接¶