Veo 3.1

Veo 3.1（产品 veo）用提示词或首帧生成视频，出片带声音（lite 可以关掉）。有三个版本，价格不同，能传的参数也不同。

版本

每个任务用 variant 选一个：

每个版本的每秒单价不同，见价格。GET /v1/products 的 prices 按版本列出各自可选的分辨率。

创建任务

用所有模型共用的创建任务接口，model 传 "veo-3.1"。接口通常不到 1 秒返回，几秒内冻结费用，一般 1–2 分钟出片；任务结束后获取结果。

请求头

请求体

• 参数检查：参数不符合所选版本、模式的规则时（例如 fast 传了 2 张图、standard 传了 generate_audio、lite 选了 1080p），返回 400 invalid_request，param 是对应的参数名，任务不会创建；传了其他参数也一样。见错误。
• 提示词：建议用英文写，效果更好。standard、fast 生成前会把提示词扩写成详细的分镜描述；lite 按原文生成。

响应：200 OK。data 是刚创建的任务，只有下面这几个字段，各字段的含义见创建任务的返回。保存 data.id，用它获取结果。任务创建后仍可能失败（例如余额不够这次的费用），以查询或回调的结果为准。

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jbq3v6n9c2x5b8m1q4w7e0r3",
    "model": "veo-3.1",
    "status": "queued",
    "error": null,
    "created_at": "2026-11-11T08:30:00Z"
  }
}

文生视频

只用 prompt 生成视频，三个版本都可以。

standard、1080p、16:9、8 秒：

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f8a2c71-9d4e-4b6a-8e1f-7c0b5a2d9e46" \
  -d '{
    "model": "veo-3.1",
    "variant": "standard",
    "mode": "text_to_video",
    "prompt": "A paper boat drifts down a rainy city street gutter, close-up, soft morning light",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8
  }'

图生视频

从 image_urls 的第 1 张图开始生成，prompt 描述接下来发生什么。

aspect_ratio 请和首帧的方向一致：横图选 16:9，竖图选 9:16（lite 也可以选 auto）。

fast、只有首帧、1080p、4 秒：

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b1d9e42-7a3c-4f85-b2e0-1c8f4a6d3b97" \
  -d '{
    "model": "veo-3.1",
    "variant": "fast",
    "mode": "image_to_video",
    "image_urls": ["https://example.com/first_frame.jpg"],
    "prompt": "The cat slowly turns its head, looks at the camera and meows, the camera slowly pushes in",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 4
  }'

lite 首尾帧（所以 duration 是 8），比例跟随首帧：

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c4e7a0b3-2f6d-4a19-9c8e-5b3d1f7a2e60" \
  -d '{
    "model": "veo-3.1",
    "variant": "lite",
    "mode": "image_to_video",
    "image_urls": [
      "https://example.com/first_frame.jpg",
      "https://example.com/last_frame.jpg"
    ],
    "prompt": "The camera slowly orbits around the cat sitting on the car hood",
    "resolution": "720p",
    "aspect_ratio": "auto",
    "duration": 8
  }'

获取结果

一般 1–2 分钟出片。任务结束（成功或失败）后用下面任一方式拿结果：

• 回调（生产环境推荐）：创建时传了 webhook_url，任务结束时会把完整的任务推送一次，见回调。
• 轮询：用 data.id 调用 GET /v1/tasks/{task_id}，间隔 15 秒以上，直到 status 为 succeeded 或 failed；多个任务用列出任务的 ids 一次查询。

失败时冻结的钱全额退回，原因在 data.error.type，见错误。完整的字段见任务对象。

素材

图片以公开的 http(s) 链接放在 image_urls 里提交。不提供上传接口，请自行托管文件。链接最长 4096 字符，必须能直接下载，不能指向 localhost 或内网、回环、保留地址。

Veo 3.1 的图片在任务提交给生成服务后才读取（创建后几秒内），这时已经冻结过费用：下载不了、读不了（损坏、格式不支持）时任务失败（invalid_media），冻结的费用全额退回。任务结束前所有链接都要保持可访问，有有效期的链接也不能提前过期。

价格

费用 = 出片时长 duration × 所选版本和分辨率的每秒单价

正在读取当前价格…

计费秒数就是请求的 duration（4、6 或 8 秒）。每秒单价只看 variant 和 resolution：模式、图片、出片带不带声音（generate_audio）都不影响价格。

例如上面的图生视频请求（fast、1080p、4 秒）冻结 4 × fast 的 1080p 每秒单价，成功后扣同样的金额，失败全额退回。冻结和扣费的通用规则见计费。

正在读取当前价格…

价格只看请求就能算出来，可以在提交前显示：当前单价从 GET /v1/products 读取，prices 每个版本、每个分辨率一行（看这一行的 variant）。价格会调整，不要写死；实际费用以查询任务返回的 billing.frozen 为准。

错误

Veo 3.1 特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误，全部失败原因见失败原因。

创建请求出错：请求返回 HTTP 错误，任务不会创建。param 是对应的参数名。

创建接口的其他错误（401、402、429 等）见创建任务 → 错误。

任务失败：创建请求成功（200），任务之后变成 failed。这种情况没有 HTTP 状态码，原因在任务的 error.type，通过查询任务或回调拿到。

所有失败的任务都已全额退回冻结金额，billing.charged 为 "0.00"。