Skip to main content

​
概述

VEO 3.1 Official 是 API易 接入 Google Veo 3.1 系列的 官转通道（透传 Google AI Studio），直连 Google veo-3.1-generate-preview / veo-3.1-fast-generate-preview 异步端点，模型 ID、响应字段、约束条件与 Google 官方完全一致。按次计费、默认分组即可调用，是目前接入门槛最低的 Veo 3.1 官方质量通道。
🎬 核心亮点：透传 Google AI Studio 官方端点 + 同步音视频原生输出 + 4 / 6 / 8 秒灵活时长 + 720p / 1080p / 4k 三档分辨率 + 按次计费 $0.3 起 + 默认分组 + 按次计费 / 按量优先令牌即可调用（无需切换专属分组）。适合广告短片、电商视频素材、社交媒体内容、产品演示 等追求官方画质 + 简单接入的生产场景。
⚠️ 以 /content 下载为准，拿到后自行落地：拿到 status: "completed" 后，通过 GET /v1/videos/{task_id}/content 拉取 MP4 二进制流并保存到你自己的 OSS / CDN，再分发给终端用户。completed 响应里可能附带一个免鉴权的 video_url 直链，但它约 24 小时后失效（以 expires_at 为准），而且不保证每个任务都有，只适合临时预览，不能当长期地址。详见下方 端点一览 段落。

文生视频 API

POST /v1/videos，纯文本提示词生成视频，JSON 请求体，最简单的入口。

图生视频 API

POST /v1/videos + multipart 上传 input_reference，让静态图片动起来。

官转 vs 官逆

与既有 VEO 3.1（官逆） 的选型对照表。

可视化接口测试

在 iCover 可视化测试工具里直接调试本接口，无需写代码。

异步任务查询 / 下载

在 API易后台查看已提交的视频任务、下载视频链接（API 之外的查询入口）。

​
让 AI Agent 帮你接入

在用 Codex / Claude Code / Cursor 开发的话，把下面这段提示词复制给它。它会先抓本页的纯文本版（任意文档页地址后加 .md），再按你项目的技术栈写代码——异步轮询、必须自己拉 MP4 落地、超时分档、4K 的硬约束这几个高频坑已经写死在要求里。

让编程 Agent 接入或排查 VEO 3.1 官转的文生视频与图生视频。复制后直接粘贴给 Codex、Claude Code、Cursor 等。

​
为什么选 API易 的 VEO 3.1 Official

对标 Google 官方 / Vertex AI 通道，针对企业生产场景在 接入门槛、稳定性、成本 三方面做了深度优化：

官转直连 · 模型 ID 一致

透传到 Google AI Studio 的 Veo 3.1 异步端点，模型 ID（veo-3.1-generate-preview / veo-3.1-fast-generate-preview）与官方完全一致，请求/响应字段、约束条件一比一对齐。

开箱即用 · 无需切分组

走 Default 默认分组、按次计费 或 按量优先 令牌均可调用（按量计费暂不支持），无需切换专属分组。老用户现有 Key 不改配置就能直接跑，是最低接入门槛的官方质量通道。

不限并发 · 企业可放量

账号池聚合透传，批量出片 / 短视频矩阵 / 广告生产等高并发场景下可线性扩容，不受 Google 单账号 Tier 限制。

按次定价 · 对比 Google 立省 60%+

veo-3.1-fast-generate-preview $0.3/次、veo-3.1-generate-preview $1.2/次，按次计费、4/6/8 秒 + 720p/1080p/4k 同价。对比 Google 官方 8 秒 1080p 立省 62-68%，叠加 充值加赠活动 进一步下降；失败任务不计费。

全球零门槛接入

无需海外服务器或代理，国内机房、家宽网络、海外节点均可直连 api.apiyi.com，省去为 Google AI Studio / Vertex AI 配置出海链路的麻烦。

专业服务 · 企业陪跑

团队深耕视频生成场景，在 prompt 工程、分辨率选型、批量生产、视频后处理等场景具备丰富经验，可为企业客户提供从 PoC 到生产上线的完整技术支持。

​
核心特性

同步音视频原生输出

Veo 3.1 系列原生输出带同步音轨的视频（环境音、对话、配乐），无需后期单独配音。音频效果通过 prompt 描述即可。

4 / 6 / 8 秒灵活时长

seconds 字符串枚举 "4" / "6" / "8"，按次计费、时长不影响单价。1080p / 4k 分辨率仅支持 "8"。

三档分辨率分级

720p / 1080p / 4k 三档，单价均一。横屏（16:9）、竖屏（9:16）灵活切换。

精准指令遵循

Veo 3.1 在镜头运动、物体物理、人物表情等细节上的指令遵循能力领先同档模型，支持丰富的镜头语言关键词（推/拉/摇/跟、俯/仰拍等）。

图生视频（input_reference）

上传一张图片作为视频起始帧，让静态画面”动起来”。详见 图生视频。

异步任务化

提交后返回 task_id，轮询状态、独立下载视频，便于批量管理和断点续传。

OpenAI 兼容协议

base_url=https://api.apiyi.com/v1 + Bearer 鉴权，HTTP / OpenAI SDK 底层 client.post() 均可调用。

失败不计费

异步模式下，生成失败、内容审核拦截、参数错误等情况均不计费，仅 status=completed 的任务才扣费。

​
模型定价

API易 使用 Pay-per-request 计费，在支持的时长和分辨率组合内统一价格，不按时长或分辨率额外加价。按 ai.google.dev/gemini-api/docs/pricing 公开价格测算，Google 官方 Veo 3.1 以秒计费；以下折扣按 8 秒视频 计算。
计费说明：
  • 按 模型名 按次结算，与时长（4/6/8 秒）、分辨率（720p/1080p/4k）、是否传 input_reference 无关——选 4K 不加价
  • 异步模式下生成失败 / 内容审核拦截 / 服务过载错误均不计费
  • 充值加赠政策见 充值加赠活动，叠加后实际成本进一步下降
  • 4K 同价但渲染慢 4–6 倍、文件大 ~10 倍，日常用 1080p 性价比更优
  • Google 官方 4K 单价 fast $0.30/秒、standard $0.60/秒，8 秒约 $2.40 / $4.80（数据来源 ai.google.dev/gemini-api/docs/pricing）

​
分组介绍

VEO 3.1 Official 在 Default 默认分组即可调用（1x），无需切换专属分组。令牌计费模式需为 按次计费 或 按量优先——按量计费暂不支持（请在 控制台 把令牌切到按次或按量优先）。
接入门槛低：VEO 3.1 Official 走默认分组 + 按次或按量优先都行，无需为它单独开分组，适合追求”现有按次令牌一行 base_url 就接入” 的团队。

​
技术规格

1080p / 4k 分辨率时 seconds 必须传 "8"，传 "4" 或 "6" 会被上游拒绝。720p 三档时长都支持。

​
端点一览

⚠️ 以 /content 下载为准，video_url 只作临时预览视频文件的标准取法是 GET /v1/videos/{task_id}/content 拉取 MP4 二进制流，需要带 Authorization: Bearer 头。这意味着：
  • completed 响应里可能附带 video_url（免鉴权直链）和 expires_at（失效时间，约 24 小时后）；不保证每个任务都有，代码要能处理没有这个字段的情况
  • 前端不能直接把 /content 端点贴到 <video> 标签——浏览器请求不带鉴权头会 401；video_url 可以临时用于预览，但过期即失效
  • 拿到 status: "completed" 后立即下载 MP4，落地到自己的 OSS / CDN，再把你自家的 URL 分发给终端用户
  • 远端视频约保留 24 小时，不要长期依赖远端 task_id 或 video_url 拿视频
域名选择：主域名 api.apiyi.com，也可使用 b.apiyi.com 等其它网关域名，响应行为一致。

​
关键参数详解

⚡ 完整参数速查表：跳转到 文生视频 - 参数说明速查 一表看全 model / prompt / seconds / size / metadata.* 的类型、必填、默认值、取值约束。本节只展开最容易踩坑的 3 个参数。

​
seconds（视频时长）

控制时长的字段名是 seconds（不是 duration），必须传字符串（"4" / "6" / "8"），传数字会被服务端拒绝并报：
常见踩坑：字段名写成 duration 会被静默忽略。duration 不是本通道识别的字段 → 被丢弃 → 时长回落到默认 4 秒：
  • 720p 等允许 4 秒的分辨率：不报错，但只出 4 秒（“传了 8s 却只出 4s” 就是这么来的）
  • 1080p / 4k：因 4 秒非法直接报错 Resolution 1080p requires duration seconds to be 8 seconds, but got 4
正确写法：请求字段用 seconds，值 "8"（字符串）。
参数识别优先级：metadata.durationSeconds > seconds > 8

​
metadata.resolution（分辨率）

参数识别优先级：metadata.resolution > size > 720p

​
⚠️ 不要传 generateAudio

Veo 3 / 3.1 原生带音频，但 generateAudio 参数不要传，上游会回 INVALID_ARGUMENT。要控制音频效果，把意图写进 prompt：
“黄昏海边的灯塔，海浪声、远处海鸟叫声，低沉的风声，电影级氛围”

​
最佳实践

1

按需选模型

  • 试水 / 批量预览 → veo-3.1-fast-generate-preview（$0.3/次）
  • 最终交付 / 4K 高清 → veo-3.1-generate-preview（$1.2/次）
  • 同 prompt + 同 seed 下两个模型各跑一次，人工挑成片
2

先调通 4 秒再放大时长

每个 prompt 先用 seconds: "4" 快速验证镜头方向、风格是否符合预期（耗时 60–90 秒、单价 $0.3），定型后再放大到 8 秒或换 1080p。
3

走异步轮询而不是同步等待

官转通道仅支持异步：POST 提交拿 task_id → 每 8–10 秒轮询 GET /v1/videos/{task_id} 直到 status: "completed" → 从 /content 下载 MP4。没有 webhook，只能轮询。
4

客户端超时分档配置

  • 720p / 1080p：3 分钟硬超时
  • 4K：10 分钟硬超时
  • POST 提交（multipart）：30 秒起步
5

完成后立即下载落地

生成完成后立即下载到自己的 OSS / CDN，远端只保留约 24 小时，不要长期依赖远端 task_id 拿视频。status 刚翻 completed 后调 /content 偶发 400，等 4 秒重试一次即可（参考客户端已内置重试）。同一个端点返回 502 则是原厂侧取不到文件，重试无效。
6

音频效果写进 prompt

不要传 generateAudio 参数（会被 INVALID_ARGUMENT 拒）。要环境音 / 对白 / BGM 直接写到 prompt 里：“海浪声、远处海鸟叫声、低沉的风声”。
7

生产侧自己限流

并发上限官方未明示，实测同时 10 个任务全部成功入队。生产侧建议 in-flight ≤ 10，对 429 / 5xx 加指数退避重试。

​
错误码与重试

建议客户端：
  • POST 提交超时 30 秒（multipart 上传可能更慢）
  • GET 轮询间隔 8–10 秒，最长等待 720p/1080p 3 分钟、4K 10 分钟
  • 对 5xx 与任务 failed 做 指数退避重试（建议 1–2 次）
  • 下载 /content 遇到 400 每 4 秒重试，最多等约 30 秒
  • /content 的 400 和 502 要分开处理：400 重试就好；502 重试无效，最多试 2 次即判失败并保留 task_id

​
常见问题

官转（本页）：透传到 Google AI Studio 官方端点，模型 ID 与 Google 官方一致（veo-3.1-generate-preview / veo-3.1-fast-generate-preview），按次 $0.3 / $1.2，仅支持异步端点。官逆（既有 VEO 3.1）：通过逆向工程接入 Google Flow，模型 ID 是 veo-3.1-fast / veo-3.1 / -fl 系列，按次 $0.15 起，价格更便宜，同时支持 同步流式 与异步两种调用，且支持首尾帧。详细对比见 官转 vs 官逆 选型表。两个通道并存，按业务需求选。
请求字段名是 seconds（字符串 "4" / "6" / "8"）。写成 duration 不会被识别，会被静默丢弃，时长回落到默认 4 秒——这是”传了 8s 却只出 4s”的根因。至于为什么必须传字符串：后端的 Go struct 把这个字段（内部名 duration）声明为 string 类型，传数字直接被解码层拒掉，报 parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string（错误信息里出现的 duration 是后端内部字段名，请求里仍然要写 seconds）。写代码时记得：字段名用 seconds、值加引号 "4" / "6" / "8"。
Veo 3 / 3.1 是 原生带音频 的视频模型，但 generateAudio 这个参数 不要传（传了会被上游回 INVALID_ARGUMENT）。要控制声音，把音频意图写进 prompt：
“黄昏海边的灯塔，海浪声、远处海鸟叫声，低沉的风声，电影级氛围”
  • 同等参数下 渲染时长基本相同（实测 720p 8 秒：fast 83s、standard 78s），fast 不是更快，而是更便宜（$0.3 vs $1.2）
  • 默认用 veo-3.1-fast-generate-preview
  • 最终交付、对画面细腻度 / 物理一致性敏感时切 veo-3.1-generate-preview
  • 建议线上 AB：同 prompt + 同 seed 下两个模型各跑一次，人工挑
绝大多数场景不推荐：
  • 同价格按次，听起来划算
  • 但渲染慢 4–6 倍（720p 80s → 4K 350s）
  • 文件大 ~10 倍（720p 4MB → 4K 40MB），带宽 / 存储成本翻倍
  • 视觉上 1080p 已经够用，大部分播放场景看不出差别
确实需要 4K 时：模型用 veo-3.1-generate-preview、seconds 必须 "8"、客户端超时 ≥ 10 分钟、异步任务做好后台处理。
  • 目前 没有 webhook，只能轮询 GET /v1/videos/{task_id}
  • 推荐轮询间隔：8 秒（实测够用，不触发限流）
  • 实测耗时：720p / 1080p 60–115 秒，4K 5–6 分钟
  • 客户端超时建议 720p/1080p 设 3 分钟，4K 设 10 分钟
400：等一下就好。 status 刚翻 completed 后立即调 /v1/videos/{task_id}/content 偶发 400，是视频文件还没同步完。这段窗口最长约 20 秒，每 4 秒重试、最多等约 30 秒即可（参考客户端已内置）。用 curl 时注意：--retry 默认不重试 400，要加 -f --retry-all-errors。502：重试没有用。 响应体形如 {"error":{"message":"Upstream service returned status 502"}}，说明任务本身生成成功了（GET /v1/videos/{task_id} 仍然返回 status: "completed"、progress: 100），只是原厂侧取不到这个视频文件。实测隔几小时再取仍然是 502，不会自愈，所以不要写成无限重试。正确处理：
  1. 最多重试 2 次，仍是 502 就判定该任务失败
  2. 保留 task_id 联系我们——这种情况该次生成已经计费，我们核实后处理
  3. 重新提交一次新任务通常正常出片，不必改 prompt
现在这种情况已经少见：大部分任务在报 completed 之前会先确认视频文件取得到，取不到的会直接变成 status: "failed"（error.message 里写明原因）并自动退回费用，不会再出现「扣了费却拿不到」。但仍不能完全排除，GET /v1/videos/{task_id} 返回 completed 不等于视频取得到，这两步要分别判断成败。
可能有，但只能临时用。completed 响应里可能附带 video_url（免鉴权直链）和 expires_at（失效时间戳，约为完成后 24 小时）。它不保证每个任务都有，过期后也取不到，所以不能当长期地址分发。标准取法：拿到 status: "completed" 后调 GET /v1/videos/{task_id}/content，返回 MP4 二进制流（需要带 Authorization: Bearer 头）。这个端点对所有任务都可用。生产侧标准做法：
  1. 后端任务完成后立即下载 MP4 → 推到自己的 OSS / CDN
  2. 把自家 CDN URL 分发给终端用户
  3. 前端 <video> 标签不要直接指向 /content 端点——浏览器请求不带鉴权头会 401；有 video_url 时可以拿来做完成后的即时预览
约 24 小时，以响应里的 expires_at 为准（没有这个字段时也按 24 小时估计）。强烈建议生成完成后立即下载落本地存储，不要长期依赖远端 task_id 或 video_url 拿视频——过期后就取不到了。
这个字段是粗粒度，只在少数几个档位之间跳（如 0 / 10 / 30 / 50 / 100），不要拿来做百分比进度条。要展示进度，要么用旋转 loading，要么按”已等待秒数 / 预期秒数”自己算。
不会。只对 status=completed 的任务计费，failed / 取消 / 内容审核拦截 / 参数错误都免费。只要任务没真正出片就不扣费。
不能字节级复现。实测同 prompt + 同 seed（88888）+ 同参数，fast 跑两次：文件大小 9.81 MB vs 9.25 MB、md5 完全不同、渲染耗时也不同。但 seed 不是装饰品：同 seed 多次结果互相聚集（5 次实测组内文件大小跨度仅 6%），不同 seed 系统性偏移（组间差距 +36.8%）。所以：
  • 想要”稳定风格” → 固定 seed
  • 想要”探索变体” → 换 seed 比换 prompt 局部词更直观
  • 想要”精确重放” → 别想了，把 mp4 存下来
当前都不支持。图生视频只能 1 张图，字段名固定 input_reference，且只接受文件或 Base64，不接受远程 URL。Google 官方 Veo 3.1 有多参考图 / 首尾帧 / 视频扩展能力，但本站官转通道暂未开放。首尾帧需求请用 VEO 3.1（官逆） 的 -fl 系列模型。
实测一口气提交 10 个任务全部成功入队，未触发拒绝。具体上限官方未明示，建议生产侧自己限流（in-flight ≤ 10），对 429 / 5xx 加指数退避重试。
  • 没有可视水印
  • 但带 Google C2PA Content Credentials 签名（urn:c2pa:...，Google C2PA Media Services 颁发），藏在 MP4 元数据里。终端用户肉眼看不到，用 C2PA 工具（如 Adobe Content Authenticity）可以验出”由 Veo 生成”
  • 二创再分发知情即可，一般不影响播放
部分可以。接口是 OpenAI 风格的（Bearer 鉴权 + /v1/...），但 OpenAI 官方 SDK 没有 videos.create 这个方法（/v1/videos 是自定义路径），多半要用 OpenAI SDK 的底层 client.post() 或直接 HTTP 调用。直接 HTTP 最省事，详见 文生视频 Playground 页的代码示例。

​
相关文档

VEO 3.1 Official 是 API易 透传 Google AI Studio 的稳定官转服务。模型 ID、响应字段、约束条件与 Google 官方完全一致，且默认分组 + 按次计费 / 按量优先 令牌即可调用——是目前接入门槛最低的官方质量通道。如有问题或建议，欢迎在控制台工单中反馈。