跳转到主要内容
异步调用说明: 适合批量处理场景,提交任务后通过轮询获取结果。如需实时交互,请使用同步调用方式

模型与定价

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. 创建视频任务

/v1/videos
创建异步视频生成任务
请求头
Content-Type: application/json
Authorization: sk-APIKEY
请求参数
prompt
string
必填
视频生成的文本描述
model
string
必填
模型名称,如 veo-3.1veo-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. 查询任务状态

/v1/videos/{video_id}
查询视频生成任务的当前状态
路径参数
video_id
string
必填
视频任务 ID(从创建接口返回)
请求示例
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 小时,建议及时下载保存。

完整调用流程

1

创建任务

调用 POST /v1/videos 接口创建视频生成任务,获取 video_id
2

轮询状态

使用 GET /v1/videos/{video_id} 接口轮询任务状态(建议每 5-10 秒轮询一次),直到状态为 completed
3

获取视频

调用 GET /v1/videos/{video_id}/content 接口获取视频 URL
4

下载视频

从返回的 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),因为需要上传图片文件。
prompt
string
必填
视频描述,建议描述画面如何运动(如「镜头缓慢推进」「人物向前走」)
model
string
必填
必须使用 -fl 后缀的模型,如 veo-3.1-flveo-3.1-landscape-fl
input_reference
file
必填
图片文件。传 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_keyAPI 密钥无效检查 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 小时,建议生成成功后及时下载保存。
大批量使用可联系客服获取企业优惠,邮箱:[email protected]

技术规格速查表

项目规格
视频时长8 秒
竖屏分辨率720 x 1280 (9:16)
横屏分辨率1280 x 720 (16:9)
音轨自动包含
URL 有效期24 小时
建议轮询间隔5-10 秒
最大等待时间10 分钟