Veo 视频生成 API 文档¶
本文档介绍如何使用 Veo 模型进行视频生成,包括文生视频、图生视频(首尾帧模式)和图生视频(参考图模式)。
支持的模型¶
| 模型 | 用途 | 图片数量 | 说明 |
|---|---|---|---|
veo_3_1-fast |
文生视频 / 参考图模式 | 0 或 1~3 | 不传图为文生,传图为参考图 |
veo_3_1-fast-fl |
首尾帧模式 | 1~2 | 1 张 = 仅首帧,2 张 = 首尾帧 |
模型选择指南:
- 文生视频:
veo_3_1-fast,不传input_reference[] - 首尾帧模式(图生视频):
veo_3_1-fast-fl,传 1~2 张图 - 参考图模式(图生视频):
veo_3_1-fast,传 1~3 张参考图
API 端点¶
请求说明¶
⚠️ 本接口仅支持
multipart/form-data,不使用application/json。 原因:JSON 方式在多图场景下不稳定,多图请一律使用 form-data。文生视频同样使用 form-data,仅不传图片字段即可。
请求头¶
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
Authorization |
string | 是 | Bearer YOUR_API_KEY |
Content-Type |
string | — | multipart/form-data |
表单字段¶
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型名称:veo_3_1-fast 或 veo_3_1-fast-fl |
prompt |
string | 是 | 文本提示词 |
size |
string | 否 | 视频尺寸,格式 widthxheight,如 1280x720、1920x1080(详见尺寸说明) |
input_reference[] |
可重复 | 否 | 图生视频时传递,同一字段名可重复多次,每次对应一张图。文生视频不携带本字段即可。 |
input_reference[] 的三种传法¶
| 方式 | 说明 |
|---|---|
| 本地文件 | multipart 文件部件,例如 curl 的 -F "input_reference[]=@/path/to/image.jpg" |
| 图片 URL | 普通表单文本,传可公网访问的图片直链,例如 -F "input_reference[]=https://example.com/a.png" |
| Base64 | 文本字段,完整 data URI,例如 -F "input_reference[]=data:image/jpeg;base64,/9j/4AAQ..." |
顺序约定:
- 首尾帧模式:第 1 个
input_reference[]为首帧,第 2 个为尾帧;仅 1 个时表示只指定首帧 - 参考图模式:最多 3 个
input_reference[],顺序为参考图 1、2、3
基础用法¶
1. 文生视频(Text-to-Video)¶
最简单的使用方式,仅通过文本描述生成视频,不传图片字段。
curl -X POST https://new.12ai.org/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=veo_3_1-fast" \
-F "prompt=一只可爱的小猫在花园里玩耍" \
-F "size=1920x1080"
2. 图生视频 · 首尾帧模式¶
使用 veo_3_1-fast-fl 模型,支持 1~2 张图片作为首尾帧。
本地文件上传¶
curl -X POST https://new.12ai.org/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=veo_3_1-fast-fl" \
-F "prompt=让这两张图之间自然过渡" \
-F "size=1280x720" \
-F "input_reference[]=@/path/to/first_frame.jpg" \
-F "input_reference[]=@/path/to/last_frame.jpg"
图片 URL¶
curl -X POST https://new.12ai.org/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=veo_3_1-fast-fl" \
-F "prompt=广告" \
-F "size=1280x720" \
-F "input_reference[]=https://example.com/first.png" \
-F "input_reference[]=https://example.com/second.jpg"
Base64 编码¶
curl -X POST https://new.12ai.org/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=veo_3_1-fast-fl" \
-F "prompt=首尾帧动画" \
-F "size=1920x1080" \
-F "input_reference[]=data:image/jpeg;base64,/9j/4AAQSkZJRg..." \
-F "input_reference[]=data:image/jpeg;base64,/9j/4AAQSkZJRg..."
Windows cmd 示例¶
curl.exe -X POST "https://new.12ai.org/v1/videos" ^
-H "Authorization: Bearer YOUR_API_KEY" ^
-F "model=veo_3_1-fast-fl" ^
-F "prompt=广告" ^
-F "size=1280x720" ^
-F "input_reference[]=https://example.com/img1.png" ^
-F "input_reference[]=https://example.com/img2.jpg"
3. 图生视频 · 参考图模式¶
使用 veo_3_1-fast 模型,支持最多 3 张参考图片引导视频风格。
本地多文件(最多 3 张)¶
curl -X POST https://new.12ai.org/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=veo_3_1-fast" \
-F "prompt=根据参考图生成视频" \
-F "size=1280x720" \
-F "input_reference[]=@/path/to/reference1.jpg" \
-F "input_reference[]=@/path/to/reference2.jpg" \
-F "input_reference[]=@/path/to/reference3.jpg"
参考图模式同样支持 URL 或 Base64,规则与首尾帧相同,每张图为一个 URL 文本或一条 Base64 data URI,最多 3 个。
响应参数¶
| 参数名 | 类型 | 说明 |
|---|---|---|
id |
string | 任务 ID |
object |
string | 对象类型,固定值 video |
model |
string | 使用的模型名称 |
status |
string | 任务状态:queued(排队中)、processing(处理中)、completed(已完成)、failed(失败) |
progress |
number | 任务进度,0-100 |
created_at |
number | 创建时间戳(秒) |
completed_at |
number | 完成时间戳(秒,仅 completed 状态返回) |
size |
string | 视频尺寸 |
提交成功(排队中)¶
{
"id": "task_xxxxxxxxxxxxx",
"object": "video",
"model": "veo_3_1-fast",
"status": "queued",
"progress": 0,
"created_at": 1709876543,
"size": "1920x1080"
}
任务完成¶
{
"id": "task_xxxxxxxxxxxxx",
"object": "video",
"model": "veo_3_1-fast",
"status": "completed",
"progress": 100,
"created_at": 1709876543,
"completed_at": 1709876600,
"size": "1920x1080"
}
查询任务状态¶
curl -X GET https://new.12ai.org/v1/videos/task_xxxxxxxxxxxxx \
-H "Authorization: Bearer YOUR_API_KEY"
响应参数与提交接口相同,完成后会包含视频 URL。
使用场景总结¶
| 场景 | 模型 | input_reference[] 数量 | 说明 |
|---|---|---|---|
| 文生视频 | veo_3_1-fast |
0(不传) | 纯文本描述生成视频 |
| 首尾帧(图生视频) | veo_3_1-fast-fl |
1~2 | 首帧 + 可选尾帧 |
| 参考图(图生视频) | veo_3_1-fast |
1~3 | 参考图引导视频风格 |
注意事项¶
- 仅 multipart:
POST /v1/videos的所有参数请使用form-data,不要使用 JSON body(多图场景易出问题) - size 尺寸参数:
- 格式为
widthxheight,如1280x720、1920x1080 - 宽 > 高 为横屏(16:9),高 > 宽 为竖屏(9:16)
- 推荐值:
1280x720(横屏 720p)、720x1280(竖屏 720p)、1920x1080(横屏 1080p)、1080x1920(竖屏 1080p) - input_reference[]:
- 字段名必须为
input_reference[](含方括号) - 多图 = 多个同名字段;文件 / URL / Base64 可混用,但需保证顺序符合首尾帧或参考图约定
- 模型选择:
- 文生视频:
veo_3_1-fast,不传input_reference[] - 首尾帧:
veo_3_1-fast-fl,1~2 张图 - 参考图:
veo_3_1-fast,1~3 张图 - URL 说明:请使用图片直链(返回图片二进制),不要传网页 HTML 地址;需鉴权的链接请先下载再改用文件上传或 Base64
- 异步处理:提交成功仅返回任务 ID,须轮询
GET /v1/videos/{task_id}获取进度与结果
完整 Python 示例¶
import requests
import time
import json
import sys
API_BASE = "https://new.12ai.org"
API_KEY = "YOUR_API_KEY"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# 测试图片
IMG1 = "https://example.com/image1.jpg"
IMG2 = "https://example.com/image2.jpg"
IMG3 = "https://example.com/image3.jpg"
# 测试场景定义
TEST_CASES = {
"1": {
"name": "文生视频",
"data": {
"model": "veo_3_1-fast",
"prompt": "一只可爱的橘猫在花园里追逐蝴蝶,慢动作镜头,电影级画质",
"size": "1920x1080"
},
"images": []
},
"2": {
"name": "图生视频 · 首尾帧(URL)",
"data": {
"model": "veo_3_1-fast-fl",
"prompt": "平滑过渡,自然变化",
"size": "1280x720"
},
"images": [IMG1, IMG2]
},
"3": {
"name": "图生视频 · 首帧(仅一张)",
"data": {
"model": "veo_3_1-fast-fl",
"prompt": "让画面动起来,镜头缓慢推进",
"size": "1280x720"
},
"images": [IMG1]
},
"4": {
"name": "图生视频 · 参考图(最多 3 张)",
"data": {
"model": "veo_3_1-fast",
"prompt": "根据参考图生成视频",
"size": "1280x720"
},
"images": [IMG1, IMG2, IMG3]
},
"5": {
"name": "竖屏文生视频(9:16)",
"data": {
"model": "veo_3_1-fast",
"prompt": "一个人在城市街道上行走",
"size": "1080x1920"
},
"images": []
}
}
# 选择测试场景
print("=" * 50)
print("Veo API 功能测试")
print("=" * 50)
for key, case in TEST_CASES.items():
print(f" {key}. {case['name']}")
print("=" * 50)
choice = sys.argv[1] if len(sys.argv) > 1 else input("请选择测试场景 (1-5): ").strip()
if choice not in TEST_CASES:
print(f"无效选择: {choice}")
sys.exit(1)
selected = TEST_CASES[choice]
print(f"\n>>> 运行测试: {selected['name']}")
# 构建 multipart/form-data 请求
data = selected["data"]
files_list = []
# 图片作为 input_reference[] 字段(URL 以文本形式传递)
for img_url in selected["images"]:
files_list.append(("input_reference[]", (None, img_url)))
print(f"请求参数: {json.dumps(data, ensure_ascii=False, indent=2)}")
if selected["images"]:
print(f"图片数量: {len(selected['images'])}")
# 提交任务
response = requests.post(
f"{API_BASE}/v1/videos",
headers=headers,
data=data,
files=files_list if files_list else None
)
result = response.json()
print(f"\nAPI 返回: {json.dumps(result, ensure_ascii=False, indent=2)}")
# 检查错误
if "error" in result:
print(f"请求失败: {result['error']}")
sys.exit(1)
task_id = result.get("id")
if not task_id:
print(f"未找到 task_id,完整响应: {result}")
sys.exit(1)
print(f"任务已提交,task_id: {task_id}")
# 轮询查询状态
while True:
response = requests.get(f"{API_BASE}/v1/videos/{task_id}", headers=headers)
status = response.json()
current_status = status.get("status", "")
progress = status.get("progress", "N/A")
print(f"状态: {current_status}, 进度: {progress}")
if current_status == "completed":
print("视频生成成功!")
break
elif current_status == "failed":
print(f"视频生成失败: {status}")
break
time.sleep(5)