异步调用 API

VEO 3.1 异步调用接口详解，适合批量处理场景

异步调用说明： 适合批量处理场景，提交任务后通过轮询获取结果。如需实时交互，请使用同步调用方式。

​

模型与定价

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.1、veo-3.1-fast 等

请求示例

cURL

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"
}'

import requests

url = "https://api.apiyi.com/v1/videos"
headers = {
    "Content-Type": "application/json",
    "Authorization": "sk-your-api-key"
}
data = {
    "prompt": "画小猫",
    "model": "veo-3.1"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const response = await fetch('https://api.apiyi.com/v1/videos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'sk-your-api-key'
  },
  body: JSON.stringify({
    prompt: '画小猫',
    model: 'veo-3.1'
  })
});

const data = await response.json();
console.log(data);

响应示例

{
  "id": "video_abc123",
  "object": "video",
  "created": 1762181811,
  "status": "queued",
  "model": "veo-3.1"
}

​

2. 查询任务状态

/v1/videos/{video_id}

查询视频生成任务的当前状态

路径参数

video_id · string · 必填

视频任务 ID（从创建接口返回）

请求示例

cURL

curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123' \
--header 'Authorization: sk-your-api-key'

import requests

video_id = "video_abc123"
url = f"https://api.apiyi.com/v1/videos/{video_id}"
headers = {
    "Authorization": "sk-your-api-key"
}

response = requests.get(url, headers=headers)
print(response.json())

const videoId = 'video_abc123';
const response = await fetch(`https://api.apiyi.com/v1/videos/${videoId}`, {
  headers: {
    'Authorization': 'sk-your-api-key'
  }
});

const data = await response.json();
console.log(data);

状态说明

状态	说明	下一步操作
queued	任务排队中	继续轮询状态
processing	任务处理中	继续轮询状态
completed	生成完成	调用获取内容接口
failed	生成失败	检查错误信息

​

3. 获取视频内容

/v1/videos/{video_id}/content

获取已生成视频的实际内容

请求示例

cURL

curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123/content' \
--header 'Authorization: sk-your-api-key'

import requests

video_id = "video_abc123"
url = f"https://api.apiyi.com/v1/videos/{video_id}/content"
headers = {
    "Authorization": "sk-your-api-key"
}

response = requests.get(url, headers=headers)
print(response.json())

const videoId = 'video_abc123';
const response = await fetch(`https://api.apiyi.com/v1/videos/${videoId}/content`, {
  headers: {
    'Authorization': 'sk-your-api-key'
  }
});

const data = await response.json();
console.log(data);

响应示例

{
  "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-fl、veo-3.1-landscape-fl 等

input_reference · file · 必填

图片文件。传 1 次为首帧模式，传 2 次为首尾帧模式

​

首帧模式示例（单图）

以一张图片作为视频开头，AI 自动生成后续画面。

cURL

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"'

import requests

url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "sk-your-api-key"}
data = {
    "prompt": "让这个画面动起来，镜头缓慢推进",
    "model": "veo-3.1-landscape-fl"
}

# 单图模式 - 首帧
files = [
    ("input_reference", ("image.jpg", open("/path/to/image.jpg", "rb"), "image/jpeg"))
]

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('prompt', '让这个画面动起来，镜头缓慢推进');
form.append('model', 'veo-3.1-landscape-fl');
form.append('input_reference', fs.createReadStream('/path/to/image.jpg'));

const response = await fetch('https://api.apiyi.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'sk-your-api-key',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log(data);

​

首尾帧模式示例（双图）

指定视频的开头和结尾画面，AI 生成中间的过渡动画。

cURL

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"'

import requests

url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "sk-your-api-key"}
data = {
    "prompt": "从白天过渡到夜晚，镜头保持不动",
    "model": "veo-3.1-landscape-fl"
}

# 双图模式 - 首尾帧
files = [
    ("input_reference", ("first.jpg", open("/path/to/first-frame.jpg", "rb"), "image/jpeg")),
    ("input_reference", ("last.jpg", open("/path/to/last-frame.jpg", "rb"), "image/jpeg"))
]

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('prompt', '从白天过渡到夜晚，镜头保持不动');
form.append('model', 'veo-3.1-landscape-fl');
form.append('input_reference', fs.createReadStream('/path/to/first-frame.jpg'));
form.append('input_reference', fs.createReadStream('/path/to/last-frame.jpg'));

const response = await fetch('https://api.apiyi.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'sk-your-api-key',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log(data);

​

响应与后续处理

帧转视频的响应格式与文生视频相同，返回 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 有效期多久？

视频 URL 有效期通常为 24 小时，建议生成成功后及时下载保存。

批量使用有优惠吗？

大批量使用可联系客服获取企业优惠，邮箱：[e-mail]

​

技术规格速查表

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