Veo 3.1 / Veo 3.1 Fast 文生视频（Google 原生协议）

官方模型 ID（路径中使用）	平台逻辑模型	定位
`veo-3.1-generate-preview`	`veo-3.1`	质量版，原生音画同出
`veo-3.1-fast-generate-preview`	`veo-3.1-fast`	速度优化版，成本更低

ModelGo 按 Google Gemini API 的 长时任务（Long-running operation） 协议原样接收 Veo 请求：predictLongRunning 创建 → operations 轮询 → 下载。请求体与 Google 文档一致（instances + parameters）；网关负责路由到供应商并计费。

使用 Google GenAI SDK 时，把 http_options.base_url 指向 https://api.modelgo.com、api_key 换成 ModelGo API Key 即可。鉴权头同时接受 x-goog-api-key: $KEY 与 Authorization: Bearer $KEY。

1. 创建任务

POST https://api.modelgo.com/v1beta/models/{model}:predictLongRunning（也接受 /v1/models/...）

bash

curl "https://api.modelgo.com/v1beta/models/veo-3.1-fast-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "A small red ball rolling slowly across a wooden table, soft daylight"}],
    "parameters": {"aspectRatio": "16:9", "resolution": "1080p", "durationSeconds": 8, "generateAudio": true}
  }'

响应

json

{"name": "models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77", "done": false}

name 是官方形态的 operation 名称，最后一段是网关任务 ID；轮询时把 name 原样拼到 /v1beta/ 之后。

2. 参数说明

字段	类型	说明
`instances[0].prompt`	string	文生视频必填；图生视频提供了 `image` 时可省略。画面内容与动作描述
`instances[0].image`	object	首帧图片（图生视频）。仅支持 URL 形态 `{"imageUri": "https://..."}` / `gcsUri`；内联 `bytesBase64Encoded` 会被拒绝
`instances[0].lastFrame`	object	尾帧图片，同上
`parameters.resolution`	string	`720p` 或 `1080p`，缺省 `720p`
`parameters.durationSeconds`	int	`4` / `6` / `8`，缺省 `8`。1080p 需使用 8 秒
`parameters.aspectRatio`	string	`16:9` 或 `9:16`，缺省 `16:9`
`parameters.generateAudio`	boolean	Veo 3.1 总是生成音轨；计费不区分音频
`parameters.negativePrompt`	string	反向提示词
`parameters.seed`	int	随机种子
`parameters.sampleCount` / `numberOfVideos`	int	只能为 `1`：一个任务一段视频，`>1` 会被拒绝
`parameters.personGeneration`	string	透传

分辨率档位

档位	输出
`720p`	1280×720（16:9）/ 720×1280（9:16），缺省
`1080p`	1920×1080 / 1080×1920

只提供以上两档。 传 4k 会在创建时被拒（HTTP 400），不会静默降档生成，也不产生费用。
一次只能创建一个视频；只接受一个 instance。

3. 轮询任务

GET https://api.modelgo.com/v1beta/{operation.name}，即 GET /v1beta/models/{model}/operations/{task_id}

bash

curl "https://api.modelgo.com/v1beta/models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77" \
  -H "x-goog-api-key: $MODELGO_API_KEY"

完成时：

json

{
  "name": "models/veo-3.1-fast-generate-preview/operations/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.ai.generativelanguage.v1beta.PredictLongRunningResponse",
    "generateVideoResponse": {
      "generatedSamples": [{"video": {"uri": "https://api.modelgo.com/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content"}}]
    }
  }
}

未完成时 done=false；失败时 done=true 且带 error.{code,message}，任务不计费。
8 秒片段通常 1–2 分钟完成，请按 5–10 秒间隔轮询并带退避。
上游偶发临时错误会使创建返回 502，不计费，重试即可。

4. 下载视频

generatedSamples[].video.uri 指向网关内容接口，与 Google 官方一致需带 API Key：

bash

curl "https://api.modelgo.com/v1/videos/gw_4a5252ef-2d5f-4a3c-9c1e-0c8b8f3f1a77/content" \
  -H "x-goog-api-key: $MODELGO_API_KEY" -o veo.mp4

返回 video/mp4（含 AAC 音轨），支持 Range。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 409，过期或不存在返回 404。

5. 完整示例（Python）

python

import os, time, requests

BASE = "https://api.modelgo.com"
H = {"x-goog-api-key": os.environ["MODELGO_API_KEY"]}

def generate(model: str, prompt: str, params: dict, out: str, timeout: int = 600) -> None:
    r = requests.post(f"{BASE}/v1beta/models/{model}:predictLongRunning",
                      json={"instances": [{"prompt": prompt}], "parameters": params}, headers=H, timeout=30)
    r.raise_for_status()
    name = r.json()["name"]
    deadline = time.time() + timeout
    while True:
        if time.time() > deadline:
            raise TimeoutError(name)
        op = requests.get(f"{BASE}/v1beta/{name}", headers=H, timeout=30).json()
        if op.get("done"):
            break
        time.sleep(8)
    if "error" in op:
        raise RuntimeError(op["error"]["message"])
    uri = op["response"]["generateVideoResponse"]["generatedSamples"][0]["video"]["uri"]
    with requests.get(uri, headers=H, stream=True, timeout=120) as c:
        c.raise_for_status()
        with open(out, "wb") as f:
            for chunk in c.iter_content(1 << 20):
                f.write(chunk)

generate("veo-3.1-fast-generate-preview", "A small red ball rolling across a wooden table",
         {"resolution": "1080p", "durationSeconds": 8, "aspectRatio": "16:9"}, "veo-fast.mp4")
generate("veo-3.1-generate-preview", "A cinematic drone shot over a misty forest at dawn",
         {"resolution": "720p", "durationSeconds": 4}, "veo.mp4")

6. 计费口径

USD 计价，按视频秒数 × 分辨率档位单价计费，结算时按当日汇率折算到账户币种。
创建时按请求的 durationSeconds 预授权冻结，任务完成后按实际交付秒数结算。
未传时长按缺省值预授权（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，四舍五入到整秒（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。
创建被拒（400）或生成失败（done=true + error）不计费，预授权自动释放。
各档单价以控制台「模型列表」中的价格为准。

常见错误

现象	原因	处理
创建返回 `400`	`resolution` 不在 720p / 1080p；`sampleCount` > 1；多个 `instances`；`image` 用了内联 base64	按参数表修正，图片改用 URL
创建返回 `502`	上游临时错误	重试；不计费
轮询 `task_not_found`	operation 名称不是本 Key 创建的任务	核对 `name` 与 Key
下载 `409` / `404`	任务未完成 / 产物过期	先轮询到 `done=true`；及时下载