Veo 3.1 视频生成

使用 EasyRouter 统一接口调用 Google Veo 3.1 全系列视频生成模型，支持文生视频、图生视频，可选生成同步音频。

Veo 3.1 是 Google 推出的新一代视频生成模型，支持文本/图片输入、最高 4K 分辨率输出，并原生支持同步语音与音效生成。EasyRouter 通过统一的 /v1/video/generations 异步任务接口对外提供服务。

Veo 3.1 是异步任务型接口：提交后立即返回 task_id，需要轮询任务状态，成功后从 data.url 下载视频。

一、支持的模型

模型 ID	版本	特点	适用场景
`veo-3.1-generate-001`	Veo 3.1	最高画质，支持 4K，原生音频	高质量创意内容、商业制作
`veo-3.1-fast-generate-001`	Veo 3.1 Fast	更快速度，均衡画质	快速迭代、批量生成
`veo-3.1-lite-generate-001`	Veo 3.1 Lite	最快速度，最低成本	原型验证、低成本场景

3 个模型统一使用同一个接口路径，仅通过 model 字段区分。所有模型均支持文生视频与图生视频，均可选择是否生成音频。

二、通用接口

2.1 提交任务

POST /v1/video/generations

请求头

Header	必填	说明
`Authorization`	✓	`Bearer sk-你的APIKey`
`Content-Type`	✓	`application/json`

请求体字段

字段	类型	必填	说明
`model`	string	✓	Veo 3.1 模型 ID，见上表
`prompt`	string	✓	视频描述提示词，支持中英文，建议英文获得最佳效果
`size`	string	—	分辨率：`720p` / `1080p` / `4000`（4K，部分模型支持），默认 `1080p`
`resolution`	string	—	同 `size`（推荐使用，与上游一致；两者并存时以本字段为准）
`duration`	int	—	视频时长（秒），可选 `4` / `6` / `8`，默认 `8`
`seconds`	string	—	`duration` 的字符串形式（兼容 OpenAI Sora API）
`aspect_ratio`	string	—	宽高比，可选 `16:9` / `9:16`，默认 `16:9`
`generate_audio`	bool	—	是否生成同步音频（语音、音效、背景音），默认 `true`（如不需要音频，强烈建议明确设为 `false` 以节省费用）
`negative_prompt`	string	—	负向提示词，描述不希望出现的内容
`seed`	int	—	随机种子（放在 `metadata.seed` 内，详见下方）
`image`	string	—	图生视频首帧图，支持 HTTP(S) URL / data URI / raw base64（见图片输入格式）
`images`	string[]	—	图生视频首帧图数组，仅 `images[0]` 生效；与 `image` 同时传时 `image` 优先
`last_frame_image`	string	—	尾帧图（与 `image` / `images[0]` 配合 → 首+尾帧插值生成过渡动画，Veo 3.1 专属）。格式同 `image`
`reference_images`	string[]	—	资产参考图数组，最多 3 张；后台会以 `referenceType="asset"` 递交上游。与 `image` / `last_frame_image` 互斥，仅支持 `duration=8`
`metadata`	object	—	Veo 原生参数容器，详见下方第三节

顶层字段已自动适配 OpenAI 风格：generate_audio / negative_prompt / aspect_ratio 等 snake_case 命名顶层字段会被自动映射到上游 Veo 的 camelCase 参数。你也可以把它们放到 metadata 里（snake_case 与 camelCase 均可），与顶层等价。

generate_audio: true 会显著提高费用（约 2 倍）。计费默认值为 true，因此如不需要音频，请明确设置 generate_audio: false 以避免按含音频费率扣费。详见第七节计费说明。

响应

{
  "id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
  "task_id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
  "object": "video",
  "model": "veo-3.1-generate-001",
  "status": "queued",
  "progress": 0,
  "created_at": 1778590105
}

2.2 查询任务状态

GET /v1/video/generations/{task_id}

响应采用 EasyRouter 统一的 {code, message, data} 包装格式。

响应（成功 / succeeded）

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
    "status": "succeeded",
    "error": null,
    "format": "mp4",
    "metadata": null,
    "url": "https://easyrouter.io/v1/videos/task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j/content"
  }
}

响应（失败 / failed）

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
    "status": "failed",
    "error": "SafetyFilterActivated: prompt violates content policy",
    "format": null,
    "metadata": null,
    "url": null
  }
}

状态枚举

状态	说明
`queued`	已提交，等待处理
`processing`	生成中
`succeeded`	已完成，`data.url` 为视频下载地址
`failed`	生成失败，`data.error` 为原因

data 字段说明

字段	类型	说明
`task_id`	string	任务 ID
`status`	string	任务状态
`error`	string / null	失败原因，成功时为 null
`format`	string / null	输出格式（如 `mp4`），处理中或失败时为 null
`metadata`	object / null	附加元数据
`url`	string / null	视频下载地址，处理中或失败时为 null

视频下载地址（data.url）为临时签名链接，24 小时有效，获取后请尽快下载或转存。

2.3 图片输入格式

image / images[0] 均支持以下三种格式，EasyRouter 会自动识别并转换为 Veo 上游所需的内联 base64：

格式	示例	说明
HTTP(S) URL	`https://example.com/foo.png`	EasyRouter 后端同步下载并 base64 编码后转发；URL 必须公网可达且未过期
data URI	`data:image/png;base64,iVBOR...`	直接透传内联数据，无需联网，适合不愿暴露图片 URL 的场景
raw base64	`iVBORw0KGgo...`（不含前缀）	无前缀的纯 base64，自动嗅探 MIME 类型

限制：

单张图片解码后大小 ≤ 20 MB
URL 形式的下载超时为 30 秒
解析失败（URL 不可达 / 超大 / base64 非法）会返回 400 parse images[0] failed: ...，不会扣费

gs:// 形式的 GCS 原生 URI 暂不支持；如使用 GCS，请改用 https://storage.googleapis.com/... HTTPS 形式。

三、metadata 高级参数

metadata 是 Veo 原生参数容器，可放置 OpenAI 风格中没有的高级参数。所有顶层字段也可以放到 metadata 内（snake_case 与 camelCase 均可），用于覆盖默认行为。

字段	类型	说明
`seed`	int	随机种子（推荐放这里）
`personGeneration` / `person_generation`	string	人物生成策略：`allow_all` / `allow_adult` / `dont_allow`
`storageUri` / `storage_uri`	string	直接把生成结果写入指定 GCS 桶路径（仅 vertex 渠道，需要权限）
`compressionQuality` / `compression_quality`	string	压缩质量：`optimized`（默认）/ `lossless`
`resizeMode` / `resize_mode`	string	图生视频缩放策略：`crop` / `fit`
`sampleCount` / `sample_count`	int	一次生成几条视频，当前固定为 1，传入会被覆盖

优先级：metadata 内已有的 camelCase > metadata 内的 snake_case > 顶层字段。也就是说同名时以 metadata camelCase 为准。

四、OpenAI 兼容接口（可选）

除 /v1/video/generations 外，也支持 OpenAI 风格的 /v1/videos 接口，两者完全等价。

提交：POST /v1/videos（请求体字段相同）

查询：GET /v1/videos/{task_id}，返回 OpenAI 扁平格式：

{
  "id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
  "object": "video",
  "model": "veo-3.1-generate-001",
  "status": "completed",
  "progress": 100,
  "created_at": 1778590105,
  "completed_at": 1778590201
}

OpenAI 兼容接口的查询响应不包含视频 URL。如需获取下载地址，请使用 /v1/video/generations/{task_id} 接口，从 data.url 获取。

五、完整调用示例

# Step 1: 提交任务
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "A golden retriever playing fetch on a sunny beach, cinematic wide shot, slow motion",
    "size": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

# Step 2: 轮询（建议间隔 10~15 秒）
curl https://easyrouter.io/v1/video/generations/task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j \
  -H "Authorization: Bearer sk-你的APIKey"

# Step 3: data.status == "succeeded" 后下载视频
curl -o output.mp4 "https://easyrouter.io/v1/videos/task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j/content"

# 开启 generate_audio: true，同步生成语音/音效/背景音
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "A jazz musician performing on a rainy street at night, neon lights reflecting on wet pavement",
    "size": "1080p",
    "duration": 8,
    "generate_audio": true
  }'

开启音频后费用约为纯视频的 2 倍，Veo 3.1 的 1080p 8 秒含音频 quota = 1,360,000。

# 通过 images 传入参考图，模型以此图为起点生成视频
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "The cat slowly opens its eyes and stretches, sunlight streaming through the window",
    "images": ["https://example.com/cat.jpg"],
    "size": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

# 9:16 竖屏 i2v + 同步音频，常见于电商短视频场景
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-001",
    "prompt": "Reference image constraint: use images[0] as the exact first frame. Preserve subject, color, logo and composition. Animate natural product motion only.",
    "images": ["https://your-bucket.example.com/product.png"],
    "size": "1080p",
    "duration": 6,
    "aspect_ratio": "9:16",
    "generate_audio": true
  }'

图片 URL 必须公网可达且未过期；私有 bucket 请用预签名 URL，否则会返回 400 parse images[0] failed: download image returned http 403。
aspect_ratio: "9:16" 必须显式传入，否则会按 size 默认生成 16:9 横屏视频。

# Veo 3.1 专属：传首帧 + 尾帧，模型生成两者之间的过渡动画
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "Smooth cinematic transition between a serene garden and a bustling city.",
    "image": "https://example.com/start.jpg",
    "last_frame_image": "https://example.com/end.jpg",
    "size": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

仅 Veo 3.1 系列支持（generate-001 / fast / lite）。
两张图都会被后端下载与 base64 编码，请确保 URL 公网可达。

# referenceImages：用多张参考图控制主体/场景一致性（与 image / last_frame_image 互斥）
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "The same character walks through a futuristic neon-lit city at night, cinematic.",
    "reference_images": [
      "https://example.com/character-front.png",
      "https://example.com/character-side.png",
      "https://example.com/scene-style.png"
    ],
    "size": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

互斥约束：reference_images 不能与 image / images / last_frame_image 同时使用，同时传会返回 400 reference_images is mutually exclusive ...。
最多 3 张，超过会返回 400 reference_images supports at most 3 entries。
仅支持 duration=8，其他时长会被上游拒绝。
后台以 referenceType="asset" 递交，Veo 3.1 不支持 style 类型。

六、三个模型对比

对比项	Veo 3.1	Veo 3.1 Fast	Veo 3.1 Lite
模型 ID	`veo-3.1-generate-001`	`veo-3.1-fast-generate-001`	`veo-3.1-lite-generate-001`
画质	最高	均衡	基础
速度（实测 8s 视频）	90130 秒	75105 秒	5080 秒
最高分辨率	4K	1080p	1080p
音频支持	✓	✓	✓
图生视频	✓	✓	✓

七、计费说明

纯视频（generate_audio: false）

模型	720p	1080p	4K
`veo-3.1-generate-001`	$0.20 / 秒	$0.20 / 秒	$0.40 / 秒
`veo-3.1-fast-generate-001`	$0.08 / 秒	$0.10 / 秒	$0.25 / 秒
`veo-3.1-lite-generate-001`	$0.03 / 秒	$0.05 / 秒	—

视频 + 音频（generate_audio: true）

模型	720p	1080p	4K
`veo-3.1-generate-001`	$0.40 / 秒	$0.40 / 秒	$0.60 / 秒
`veo-3.1-fast-generate-001`	$0.10 / 秒	$0.12 / 秒	$0.30 / 秒
`veo-3.1-lite-generate-001`	$0.05 / 秒	$0.08 / 秒	—

quota 换算公式：

quota = modelPrice × QuotaPerUnit × groupRatio × pricingRatio × seconds

QuotaPerUnit = 500,000
groupRatio   = 1.0（生产 default 组）

示例（veo-3.1-generate-001，1080p，8 秒，含音频）：
  modelPrice   = 0.20
  pricingRatio = 2.0（含音频时翻倍）
  quota = 0.20 × 500,000 × 1 × 2.0 × 8 = 1,600,000

示例（veo-3.1-lite-generate-001，1080p，8 秒，纯视频）：
  modelPrice   = 0.03
  pricingRatio ≈ 1.667（1080p 系数）
  quota = 0.03 × 500,000 × 1 × 1.667 × 8 ≈ 200,000

任务失败（failed）时 EasyRouter 会自动退款，无需手动处理。

八、轮询建议

项	建议
轮询间隔	10~15 秒，不低于 5 秒
终态判断	`data.status == "succeeded"` 或 `data.status == "failed"`
总超时时间	建议 5 分钟
典型耗时（实测 8s 视频）	Lite：50~~80 秒；Fast：75~~105 秒；Standard：90~130 秒
视频 URL 有效期	24 小时，获取后立即下载或转存

简易轮询脚本（Bash）

#!/bin/bash
TID="task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j"
KEY="sk-你的APIKey"
while true; do
  RESP=$(curl -sS "https://easyrouter.io/v1/video/generations/$TID" \
    -H "Authorization: Bearer $KEY")
  echo "$RESP"
  STATUS=$(echo "$RESP" | python3 -c \
    "import sys,json;print(json.load(sys.stdin)['data'].get('status',''))")
  case "$STATUS" in
    succeeded|failed) break ;;
  esac
  sleep 15
done

九、错误处理

HTTP 错误

状态码	原因	处理
`400`	参数错误（缺少 `prompt`、非法 `duration` 值，或图片解析失败 `parse images[0] failed: ...`）	检查请求体字段；图片相关错误见 FAQ
`401`	API Key 无效或过期	检查 Authorization 头
`403`	API Key 无权访问此模型	检查 token 模型白名单
`402`	余额不足	前往 EasyRouter 控制台充值

任务失败（failed）

常见原因	处理建议
内容安全策略拦截（`data.error` 包含安全审核原因）	调整 prompt，避免敏感内容；添加 `negative_prompt`
图片 URL 无法访问	确保 `images` 中的 URL 公开可访问、未过期
`duration` 值不在支持范围	使用 `4` / `6` / `8` 之一
模型不支持 4K	`veo-3.1-lite-generate-001` 不支持 `4000` 分辨率

一、支持的模型

二、通用接口

2.1 提交任务

请求头

请求体字段

响应

2.2 查询任务状态

响应（成功 / succeeded）

响应（失败 / failed）

状态枚举

data 字段说明

2.3 图片输入格式

三、metadata 高级参数

四、OpenAI 兼容接口（可选）

五、完整调用示例

六、三个模型对比

七、计费说明

纯视频（generate_audio: false）

视频 + 音频（generate_audio: true）

八、轮询建议

简易轮询脚本（Bash）

九、错误处理

HTTP 错误

任务失败（failed）

十、常见问题

目录

Veo 3.1 视频生成

Veo 3.1 和 Veo 3.1 Fast / Lite 该如何选择？

generate_audio 会生成什么类型的音频？

duration 只能是 4/6/8 秒吗？

图生视频支持几张参考图？

图片支持哪些输入格式？

图片下载失败会怎样？

4K 分辨率（size: 4000）所有模型都支持吗？

同一 seed 能复现相同结果吗？

视频结果 URL 什么时候过期？

目录