Veo 3.1

Google Veo 3.1 视频生成模型，支持文生视频、图生视频、首尾帧生视频和素材生视频，自带背景音乐。

模型

模型名称	模式	宽高比
`veo-3`	fast（默认）、quality、lite	16:9, 9:16, Auto

定价

按 mode + resolution 计费：

模式	720p	1080p	4k
fast	40 credits ($0.20)	50 credits ($0.25)	120 credits ($0.60)
quality	300 credits ($1.50)	310 credits ($1.55)	380 credits ($1.90)
lite	20 credits ($0.10)	30 credits ($0.15)	100 credits ($0.50)

创建任务

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "A dog playing in a park, cinematic lighting",
      "mode": "fast",
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

请求体

字段	类型	必填	说明
`model`	string	是	必须为 `veo-3`
`input`	object	是	生成参数，见下方
`callback_url`	string	否	接收任务完成/失败通知的 URL

Input 对象

字段	类型	必填	说明
`prompt`	string	是	文本描述
`mode`	string	否	`fast`（默认）、`quality` 或 `lite`
`resolution`	string	否	`720p`（默认）、`1080p` 或 `4k`
`aspect_ratio`	string	否	`16:9`（默认）、`9:16` 或 `Auto`
`generation_type`	string	否	生成模式，详见生成模式
`image_urls`	string[]	否	图片 URL，用于图生视频模式
`enable_translation`	boolean	否	默认为 `true`，生成前自动将提示词翻译为英文
`seeds`	integer	否	随机种子（10000-99999），控制生成随机性
`watermark`	string	否	水印文本

生成模式

值	说明
`TEXT_2_VIDEO`	纯文本生成视频（不传 generation_type 且无图片时默认）
`FIRST_AND_LAST_FRAMES_2_VIDEO`	首尾帧模式。1 张图片作首帧，2 张图片时第二张作尾帧
`REFERENCE_2_VIDEO`	素材生视频。支持 1-3 张参考图片。仅 mode=fast 支持，且宽高比必须为 `16:9` 或 `9:16`

不指定 generation_type 时，系统根据是否提供 image_urls 自动判断。

示例：文生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "无人机航拍日落时分的山脉，电影级光影效果",
      "mode": "fast",
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

示例：图生视频（首尾帧）

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "人物从公园走到城市中心",
      "generation_type": "FIRST_AND_LAST_FRAMES_2_VIDEO",
      "resolution": "720p",
      "image_urls": [
        "https://example.com/start.jpg",
        "https://example.com/end.jpg"
      ],
      "aspect_ratio": "16:9"
    }
  }'

示例：素材生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "以这些图片为参考，生成一段产品展示视频",
      "generation_type": "REFERENCE_2_VIDEO",
      "mode": "fast",
      "resolution": "720p",
      "image_urls": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ],
      "aspect_ratio": "16:9"
    }
  }'

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "cbf6b69d-4f03-4817-8ed7-94c0292184a8"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态变化：pending -> processing -> completed 或 failed。

处理中

{
  "id": "e717a5ee-2ed4-47f4-8cc3-53394f1abb35",
  "status": "processing",
  "model": "veo-3",
  "created_at": 1774706165,
  "progress": null
}

完成

{
  "id": "7d89c51e-9430-410e-909e-df347131ebaa",
  "status": "completed",
  "model": "veo-3",
  "created_at": 1774790227,
  "completed_at": 1774796529,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/04/02/abc123.mp4"
    ],
    "metadata": {
      "resolution": "720p"
    }
  }
}

视频 URL 长期有效。所有视频默认包含背景音乐。

失败

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "veo-3",
  "created_at": 1774793758,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

任务失败时，预扣的积分会自动退还。

回调 (Callback)

创建任务时传入 callback_url，系统会在任务完成或失败时自动向你的 URL 发送 POST 请求。格式与查询任务返回一致。

视频扩展

使用 extend_task_id 对已完成的视频进行扩展生成：

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-extend",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "继续这个场景，镜头缓慢拉远",
      "extend_task_id": "原始任务的 upstream task id"
    }
  }'

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。