跳转至

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 端点

POST /v1/videos              # 提交视频生成任务
GET  /v1/videos/:task_id     # 查询任务状态

请求说明

⚠️ 本接口仅支持 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-fastveo_3_1-fast-fl
prompt string 文本提示词
size string 视频尺寸,格式 widthxheight,如 1280x7201920x1080(详见尺寸说明)
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"
}

查询任务状态

GET /v1/videos/:task_id
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 参考图引导视频风格

注意事项

  1. 仅 multipartPOST /v1/videos 的所有参数请使用 form-data,不要使用 JSON body(多图场景易出问题)
  2. size 尺寸参数
  3. 格式为 widthxheight,如 1280x7201920x1080
  4. 宽 > 高 为横屏(16:9),高 > 宽 为竖屏(9:16)
  5. 推荐值:1280x720(横屏 720p)、720x1280(竖屏 720p)、1920x1080(横屏 1080p)、1080x1920(竖屏 1080p)
  6. input_reference[]
  7. 字段名必须为 input_reference[](含方括号)
  8. 多图 = 多个同名字段;文件 / URL / Base64 可混用,但需保证顺序符合首尾帧或参考图约定
  9. 模型选择
  10. 文生视频:veo_3_1-fast,不传 input_reference[]
  11. 首尾帧:veo_3_1-fast-fl,1~2 张图
  12. 参考图:veo_3_1-fast,1~3 张图
  13. URL 说明:请使用图片直链(返回图片二进制),不要传网页 HTML 地址;需鉴权的链接请先下载再改用文件上传或 Base64
  14. 异步处理:提交成功仅返回任务 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)