Veo 3.1 视频生成 API 文档

概述

Google Veo 3.1 视频生成接口，支持文生视频（text-to-video）、图生视频（image-to-video）、参考图生视频（reference-to-video）和视频扩展（extend）四种模式。

Base URL: https://api.apiverse.ai

认证方式

所有接口均需要在请求头中携带 Token 进行认证：

Authorization: Bearer {YOUR_AUTH_TOKEN}

快速开始

cURL 示例

创建文生视频任务

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/veo-3.1" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A dog playing in a park with sunshine",
    "genType": "t2v",
    "model": "fast",
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }'

创建图生视频任务

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/veo-3.1" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The scene comes alive with gentle motion",
    "genType": "i2v",
    "imageUrls": ["https://example.com/image1.jpg"],
    "model": "quality",
    "resolution": "4k",
    "aspectRatio": "16:9"
  }'

创建首尾帧视频任务（2张图片）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/veo-3.1" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Smooth transition between the two scenes",
    "genType": "i2v",
    "imageUrls": ["https://example.com/first_frame.jpg", "https://example.com/last_frame.jpg"],
    "model": "fast",
    "resolution": "720p"
  }'

创建参考图生视频任务

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/veo-3.1" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Generate a video based on this reference material",
    "genType": "r2v",
    "imageUrls": ["https://example.com/reference.jpg"],
    "model": "fast",
    "resolution": "720p"
  }'

创建视频扩展任务

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/veo-3.1" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The dog continues running and jumping over obstacles",
    "genType": "extend",
    "sourceTaskId": "veo_task_abc123",
    "model": "fast"
  }'

查询任务状态

curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \
  -H "Authorization: Bearer your_auth_token_here"

接口列表

1. 创建 Veo 3.1 视频生成任务

POST /api/v2/open/aigc/veo-3.1

创建一个 Veo 3.1 视频生成任务。

Content-Type: application/json

请求参数

参数	类型	必填	说明
prompt	string	是	视频描述提示词
genType	string	否	生成类型：`t2v`(文生视频,默认) / `i2v`(图生视频) / `r2v`(参考图生视频) / `extend`(视频扩展)
imageUrls	string[]	条件	图片URL列表。i2v: 1-2张(1张=单帧生成, 2张=首尾帧过渡)；r2v: 1-3张
model	string	否	模型选择：`quality`(最高画质) / `fast`(高性价比,默认) / `lite`(最具成本效益)
resolution	string	否	输出分辨率：`720p`(默认) / `1080p` / `4k`
aspectRatio	string	否	宽高比：`16:9`(默认) / `9:16` / `auto`
watermark	string	否	水印文本（可选）
enableTranslation	boolean	否	是否翻译提示词为英文，默认true
sourceTaskId	string	条件	源任务ID（extend时必填，必须是 Veo 3.1 生成的任务）
seeds	int	否	随机种子（extend时可选，范围10000-99999）
callbackUrl	string	否	任务完成后的回调通知 URL

说明：
- r2v 模式仅支持 fast 模型
- i2v 传1张图片：基于该图片生成视频；传2张图片：首帧→尾帧过渡视频
- extend 只能扩展通过 Veo 3.1 生成的视频
- 所有视频默认包含背景音频
- 创建任务时会预扣费，余额不足将返回错误

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID，用于查询任务状态
data.status	string	任务状态，创建时固定为 `processing`
data.createdAt	string	创建时间

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260506150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-06 15:00:00"
  }
}

余额不足

{
  "code": 40001,
  "msg": "余额不足: 当前余额 0.0100, 需要 0.1500",
  "data": null
}

2. 查询任务状态

GET /api/v2/open/aigc/{taskId}

查询单个任务的执行状态。

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260506150000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/05/06/output_001.mp4"
    ],
    "createdAt": "2026-05-06 15:00:00",
    "updatedAt": "2026-05-06 15:02:30"
  }
}

3. 批量查询任务状态

POST /api/v2/open/aigc/batch

批量查询多个任务的执行状态（最多 100 个）。

4. 查询账户余额

GET /api/v2/open/balance

回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 callbackUrl，系统会向该 URL 发送 POST 请求。

回调请求

Headers

Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}

Body

{
  "event": "task.completed",
  "taskId": "task_20260506150000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output_001.mp4"],
  "errorMsg": "",
  "timestamp": "2026-05-06T15:02:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}

错误码

code	说明
0	成功
10002	参数缺失或格式错误
10005	API Key 无效或缺失
30003	任务不存在
40001	余额不足
90003	服务器内部错误

模型对比

模型	特点	适用场景
Quality	最高画质，生成时间较长	正式作品、高质量内容
Fast	高性价比，画质出色	日常使用、快速迭代
Lite	最低成本，速度最快	批量生成、原型验证

最佳实践

1. 轮询策略

建议的轮询间隔：
- 前 60 秒：每 5 秒查询一次
- 60 秒后：每 10 秒查询一次

2. 使用回调

生产环境建议使用回调通知而非轮询。

3. 处理时间参考

Quality 模式：通常 2 ~ 5 分钟
Fast 模式：通常 30 秒 ~ 2 分钟
Lite 模式：通常 20 秒 ~ 1 分钟
视频扩展：通常 1 ~ 3 分钟

4. 提示词建议

建议使用英文提示词（默认会自动翻译）
详细描述动作、场景、风格
i2v 时描述图片如何动起来
extend 时描述扩展内容如何衔接

5. 余额管理

创建任务前建议先查询余额
任务成功后会从冻结余额中扣费
任务失败后冻结金额会自动退还到可用余额