异步调用说明: 适合批量处理场景,提交任务后通过轮询获取结果。如需实时交互,请使用同步调用方式。
模型与定价
VEO 3.1 提供 8 种模型变体,命名规则如下:
- 基础名称:
veo-3.1
-landscape:横屏模式 (1280x720),默认为竖屏 (720x1280)
-fast:快速生成版本,速度更快、价格更低
-fl:Frame-to-Video 模式,支持首尾帧转视频
| 模型名 | 描述 | 分辨率 | 价格 |
|---|
veo-3.1 | 默认竖屏视频 | 720 x 1280 | $0.25 |
veo-3.1-fl | 竖屏+首尾帧转视频 | 720 x 1280 | $0.25 |
veo-3.1-fast | 竖屏+快速 | 720 x 1280 | $0.15 |
veo-3.1-fast-fl | 竖屏+快速+首尾帧转视频 | 720 x 1280 | $0.15 |
veo-3.1-landscape | 横屏视频 | 1280 x 720 | $0.25 |
veo-3.1-landscape-fl | 横屏+首尾帧转视频 | 1280 x 720 | $0.25 |
veo-3.1-landscape-fast | 横屏+快速 | 1280 x 720 | $0.15 |
veo-3.1-landscape-fast-fl | 横屏+快速+首尾帧转视频 | 1280 x 720 | $0.15 |
按成功计费: 仅对成功生成的视频收费,生成失败不产生费用。所有模型生成的视频时长为 8 秒,自动包含音轨。
API 端点
1. 创建视频任务
请求头
Content-Type: application/json
Authorization: sk-APIKEY
请求参数
模型名称,如 veo-3.1、veo-3.1-fast 等
请求示例
curl --location --request POST 'https://api.apiyi.com/v1/videos' \
--header 'Authorization: sk-your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
"prompt": "画小猫",
"model": "veo-3.1"
}'
响应示例
{
"id": "video_abc123",
"object": "video",
"created": 1762181811,
"status": "queued",
"model": "veo-3.1"
}
2. 查询任务状态
路径参数
请求示例
curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123' \
--header 'Authorization: sk-your-api-key'
状态说明
| 状态 | 说明 | 下一步操作 |
|---|
queued | 任务排队中 | 继续轮询状态 |
processing | 任务处理中 | 继续轮询状态 |
completed | 生成完成 | 调用获取内容接口 |
failed | 生成失败 | 检查错误信息 |
3. 获取视频内容
/v1/videos/{video_id}/content
获取已生成视频的实际内容
请求示例
curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123/content' \
--header 'Authorization: sk-your-api-key'
响应示例
{
"id": "video_abc123",
"object": "video",
"created": 1762181811,
"status": "completed",
"model": "veo-3.1",
"prompt": "画小猫",
"url": "https://veo-video.gptkey.asia/assets/flow/xxx.mp4",
"duration": 8,
"resolution": "720x1280"
}
视频 URL 有效期通常为 24 小时,建议及时下载保存。
完整调用流程
创建任务
调用 POST /v1/videos 接口创建视频生成任务,获取 video_id
轮询状态
使用 GET /v1/videos/{video_id} 接口轮询任务状态(建议每 5-10 秒轮询一次),直到状态为 completed
获取视频
调用 GET /v1/videos/{video_id}/content 接口获取视频 URL
Python 完整示例
import requests
import time
class VEOClient:
"""VEO 3.1 异步调用客户端"""
def __init__(self, api_key: str, base_url: str = "https://api.apiyi.com"):
self.base_url = base_url
self.headers = {
"Content-Type": "application/json",
"Authorization": api_key
}
def create_video(self, prompt: str, model: str = "veo-3.1") -> str:
"""创建视频任务,返回 video_id"""
response = requests.post(
f"{self.base_url}/v1/videos",
headers=self.headers,
json={"prompt": prompt, "model": model}
)
response.raise_for_status()
return response.json()["id"]
def get_status(self, video_id: str) -> dict:
"""查询任务状态"""
response = requests.get(
f"{self.base_url}/v1/videos/{video_id}",
headers=self.headers
)
response.raise_for_status()
return response.json()
def get_content(self, video_id: str) -> dict:
"""获取视频内容"""
response = requests.get(
f"{self.base_url}/v1/videos/{video_id}/content",
headers=self.headers
)
response.raise_for_status()
return response.json()
def wait_for_completion(self, video_id: str, timeout: int = 600, interval: int = 5) -> dict:
"""等待任务完成"""
start_time = time.time()
while time.time() - start_time < timeout:
status_data = self.get_status(video_id)
status = status_data.get("status")
if status == "completed":
return self.get_content(video_id)
elif status == "failed":
raise Exception(f"视频生成失败: {status_data}")
print(f"任务进行中... 状态: {status}")
time.sleep(interval)
raise TimeoutError("等待超时")
# 使用示例
if __name__ == "__main__":
client = VEOClient("sk-your-api-key")
try:
# 1. 创建任务
video_id = client.create_video(
prompt="一只猫咪在阳光下的花园里漫步",
model="veo-3.1-fast"
)
print(f"任务已创建,ID: {video_id}")
# 2. 等待完成并获取结果
result = client.wait_for_completion(video_id)
print(f"视频生成成功!")
print(f"视频URL: {result['url']}")
print(f"分辨率: {result['resolution']}")
except Exception as e:
print(f"错误: {e}")
帧转视频模式
使用 -fl 后缀的模型支持首尾帧转视频功能,可以将静态图片转换为动态视频。
| 模式 | 图片数量 | 说明 |
|---|
| 首帧模式 | 1 张 | 以图片作为视频开头,AI 自动续编后续内容 |
| 首尾帧模式 | 2 张 | 以第一张为开头、第二张为结尾,AI 生成中间过渡 |
请求参数
帧转视频请求需要使用 multipart/form-data 格式(不是 JSON),因为需要上传图片文件。
视频描述,建议描述画面如何运动(如「镜头缓慢推进」「人物向前走」)
必须使用 -fl 后缀的模型,如 veo-3.1-fl、veo-3.1-landscape-fl 等
图片文件。传 1 次为首帧模式,传 2 次为首尾帧模式
首帧模式示例(单图)
以一张图片作为视频开头,AI 自动生成后续画面。
curl --location --request POST 'https://api.apiyi.com/v1/videos' \
--header 'Authorization: sk-your-api-key' \
--form 'prompt="让这个画面动起来,镜头缓慢推进"' \
--form 'model="veo-3.1-landscape-fl"' \
--form 'input_reference=@"/path/to/image.jpg"'
首尾帧模式示例(双图)
指定视频的开头和结尾画面,AI 生成中间的过渡动画。
curl --location --request POST 'https://api.apiyi.com/v1/videos' \
--header 'Authorization: sk-your-api-key' \
--form 'prompt="从白天过渡到夜晚,镜头保持不动"' \
--form 'model="veo-3.1-landscape-fl"' \
--form 'input_reference=@"/path/to/first-frame.jpg"' \
--form 'input_reference=@"/path/to/last-frame.jpg"'
响应与后续处理
帧转视频的响应格式与文生视频相同,返回 video_id 后需要轮询获取结果:
{
"id": "video_xyz789",
"object": "video",
"created": 1762181811,
"status": "queued",
"model": "veo-3.1-landscape-fl"
}
后续流程请参考上方的完整调用流程章节。
使用建议
首帧模式适用场景
- 让静态图片「动起来」
- 产品展示动画
- 人物照片生成动态视频
首尾帧模式适用场景
- 场景转换(白天→夜晚、四季变化)
- 表情变化动画
- 物体变形过渡
提示词技巧:使用帧转视频时,prompt 应描述「画面如何运动」而非「画面内容」。例如:「镜头缓慢推进」「人物转头微笑」「花朵逐渐绽放」。
错误处理
| 错误码 | 说明 | 解决方案 |
|---|
invalid_api_key | API 密钥无效 | 检查 API 密钥是否正确 |
invalid_model | 模型不存在 | 使用支持的模型名称 |
invalid_prompt | 提示词无效 | 检查提示词长度和内容 |
video_not_found | 视频任务不存在 | 检查 video_id 是否正确 |
video_not_ready | 视频尚未生成完成 | 继续轮询任务状态 |
quota_exceeded | 配额超限 | 联系客服增加配额 |
错误响应格式
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key provided",
"type": "authentication_error"
}
}
常见问题
- 性价比优先:选择
-fast 系列($0.15/视频)
- 质量优先:选择标准系列($0.25/视频)
- 需要图片转视频:选择
-fl 系列
- 横屏内容:选择
-landscape 系列
- 快速模型 (
-fast):约 30-60 秒
- 标准模型:约 1-2 分钟
建议轮询间隔设置为 5-10 秒。
视频 URL 有效期通常为 24 小时,建议生成成功后及时下载保存。
技术规格速查表
| 项目 | 规格 |
|---|
| 视频时长 | 8 秒 |
| 竖屏分辨率 | 720 x 1280 (9:16) |
| 横屏分辨率 | 1280 x 720 (16:9) |
| 音轨 | 自动包含 |
| URL 有效期 | 24 小时 |
| 建议轮询间隔 | 5-10 秒 |
| 最大等待时间 | 10 分钟 |