Google Veo 3.1 视频生成 API 国内完整教程（2026）

TL;DR — Veo 3.1 是 Google 当前最强视频生成模型系列，2026 年 3 月加入 Lite 版后三档覆盖 $0.05-$0.60/秒，全系列原生同步音频。国内无法直连 Google API，用 ofox 的 Gemini Native 代理只换 base URL 和 Key，其他代码不动。

Veo 3.1 三档版本，先选好再动手

Veo 3.1 系列目前有三个模型 ID，对应不同价格和画质上限：

定价按分辨率计算，Pro 在 4K 为 $0.60/秒。数据来源：Gemini API 定价页（2026 年 4 月）。ofox 上的实际定价见 ofox.ai/zh/models。

选哪个：开发联调用 Lite 省成本，正式生产跑 Fast（画质和速度都够用），需要广告素材或 4K 输出才上 Pro。三档全部原生带音频，背景音、音效、人声一步出来，不用单独配音。

Veo 3.1 比 3.0 多了两个参数：referenceImages（最多 3 张风格参考图）和 video（视频续写）。做风格统一的长视频，以前很难保持连贯，现在有了实际可用的抓手。

国内为什么连不上，怎么绕

Google 的 Gemini API（Veo 3.1 走这条通道）需要请求来自 Google 服务可用地区，国内 IP 直接请求会收到 403 或连接超时。

ofox 的 Gemini Native 协议是一个透明代理：用 https://api.ofox.ai/gemini 替换 Google 的 https://generativelanguage.googleapis.com，用 ofox API Key 替换 Google API Key，其他参数、请求体、响应格式完全一致。

还没有 ofox 账号的，去 ofox.ai 注册并创建 API Key，充值余额后即可调用。

文字生成视频：完整调用流程

Veo 3.1 是异步 API，分两步走：先提交生成请求，拿到 operation ID；再轮询状态，done: true 后取视频链接。

提交请求

curl -X POST "https://api.ofox.ai/gemini/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instances":[{"prompt":"a cat chasing a butterfly in golden sunlight, cinematic"}],"parameters":{"aspectRatio":"16:9","durationSeconds":"6","resolution":"720p"}}'

正常响应：{"name": "operations/xxx-yyy-zzz", "done": false}

轮询结果

curl "https://api.ofox.ai/gemini/v1beta/operations/xxx-yyy-zzz" \
  -H "x-goog-api-key: $OFOX_API_KEY"

done: true 时，从 response.generateVideoResponse.generatedSamples[0].video.uri 取视频下载地址，生成结果保留约 48 小时，建议及时下载。

Python 示例

提交阶段：

import requests, os
HEADERS = {"x-goog-api-key": os.environ["OFOX_API_KEY"], "Content-Type": "application/json"}
BASE = "https://api.ofox.ai/gemini/v1beta"
r = requests.post(f"{BASE}/models/veo-3.1-fast-generate-preview:predictLongRunning",
    headers=HEADERS,
    json={"instances": [{"prompt": "a cat chasing a butterfly, cinematic"}],
          "parameters": {"aspectRatio": "16:9", "durationSeconds": "6"}})
op_name = r.json()["name"]

轮询阶段：

import time
while True:
    result = requests.get(f"{BASE}/{op_name}", headers=HEADERS).json()
    if result.get("done"):
        print(result["response"]["generateVideoResponse"]["generatedSamples"][0]["video"]["uri"])
        break
    time.sleep(10)

6 秒视频通常在 30-90 秒内完成，sleep(10) 是合理的轮询频率，没必要更频繁。

图片生成视频（Image-to-Video）

把起始帧图片以 base64 编码放进 instances[].image，其他流程与文字生成相同：

import base64, requests, os
HEADERS = {"x-goog-api-key": os.environ["OFOX_API_KEY"], "Content-Type": "application/json"}
BASE = "https://api.ofox.ai/gemini/v1beta"
img = base64.b64encode(open("start.jpg", "rb").read()).decode()
r = requests.post(f"{BASE}/models/veo-3.1-generate-preview:predictLongRunning",
    headers=HEADERS,
    json={"instances": [{"prompt": "waves crashing on rocks, slow motion",
          "image": {"bytesBase64Encoded": img, "mimeType": "image/jpeg"}}],
          "parameters": {"durationSeconds": "4", "aspectRatio": "16:9"}})

图片格式支持 JPEG 和 PNG，建议分辨率不低于 720p，过低的输入图会降低输出质量。

Veo 3.1 专属：风格参考图与视频续写

风格参考图走 referenceImages，最多传 3 张，Veo 3.0 没有这个参数：

json={
  "instances": [{"prompt": "a cityscape at dusk",
    "referenceImages": [{"bytesBase64Encoded": style_b64, "mimeType": "image/jpeg"}]}],
  "parameters": {"durationSeconds": "6"}
}

视频续写用 instances[].video，把现有片段作输入，往后接着生成，传法和 image 一样。做超过 8 秒的长序列靠这个拼。

参数速查

"4k" 只有 Pro 版支持，Fast 最高 1080p，Lite 最高 720p。

常见报错处理

OPERATION_FAILED：多半是 prompt 踩了内容审查（暴力、成人内容、高相似度真实人物），或者 personGeneration 配置跟请求类型对不上。换 prompt 试试，或把 personGeneration 调成 allow_all。

视频链接打不开：生成结果 URI 大概 24 小时失效，拿到就下载，别放着等。

收到 403：确认在用 ofox Key，不是 Google 原生 Key。另外检查账户余额。

更多 API 报错处理见AI API 报错排查大全——覆盖国内调用海外 API 的高频问题。

成本估算参考

以 Google 官方定价为基准：

• 6 秒 Lite（720p）：$0.30
• 6 秒 Fast（720p）：$0.60 / Fast（1080p）：$0.72
• 6 秒 Pro（1080p）：$2.40 / Pro（4K）：$3.60

实际批量生产时，先用 Lite 把 prompt 跑顺，确认效果后再切 Fast 或 Pro 出正式版，开发阶段能省下 60-80% 的费用。

扩展阅读

• Gemini 3.1 Pro API 国内接入完整指南 — 同一个 ofox Key，文字和多模态走 Gemini 3.1，视频走 Veo 3.1，base URL 相同，两用不冲突。

• AI API 中转站推荐 2026：主流平台对比评测 — 如果还在多家平台之间比较，这里有横向数据可以参考。