> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 异步调用 API

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

<Info>
  **异步调用说明：** 适合批量处理场景，提交任务后通过轮询获取结果。如需实时交互，请使用[同步调用方式](/api-capabilities/veo/quick-start)。
</Info>

## 模型与定价

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 |

<Note>
  **按成功计费：** 仅对成功生成的视频收费，生成失败不产生费用。所有模型生成的视频时长为 **8 秒**，自动包含音轨。
</Note>

## API 端点

### 1. 创建视频任务

<ParamField method="POST" path="/v1/videos">
  创建异步视频生成任务
</ParamField>

**请求头**

```text theme={null}
Content-Type: application/json
Authorization: sk-APIKEY
```

**请求参数**

<ParamField body="prompt" type="string" required>
  视频生成的文本描述
</ParamField>

<ParamField body="model" type="string" required>
  模型名称，如 `veo-3.1`、`veo-3.1-fast` 等
</ParamField>

**请求示例**

<CodeGroup>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

**响应示例**

```json theme={null}
{
  "id": "video_abc123",
  "object": "video",
  "created": 1762181811,
  "status": "queued",
  "model": "veo-3.1"
}
```

### 2. 查询任务状态

<ParamField method="GET" path="/v1/videos/{video_id}">
  查询视频生成任务的当前状态
</ParamField>

**路径参数**

<ParamField path="video_id" type="string" required>
  视频任务 ID（从创建接口返回）
</ParamField>

**请求示例**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123' \
  --header 'Authorization: sk-your-api-key'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

**状态说明**

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

### 3. 获取视频内容

<ParamField method="GET" path="/v1/videos/{video_id}/content">
  获取已生成视频的实际内容
</ParamField>

**请求示例**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123/content' \
  --header 'Authorization: sk-your-api-key'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

**响应示例**

```json theme={null}
{
  "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"
}
```

<Info>
  视频 URL 有效期通常为 24 小时，建议及时下载保存。
</Info>

## 完整调用流程

<Steps>
  <Step title="创建任务">
    调用 `POST /v1/videos` 接口创建视频生成任务，获取 `video_id`
  </Step>

  <Step title="轮询状态">
    使用 `GET /v1/videos/{video_id}` 接口轮询任务状态（建议每 5-10 秒轮询一次），直到状态为 `completed`
  </Step>

  <Step title="获取视频">
    调用 `GET /v1/videos/{video_id}/content` 接口获取视频 URL
  </Step>

  <Step title="下载视频">
    从返回的 URL 下载视频文件并保存
  </Step>
</Steps>

## Python 完整示例

```python theme={null}
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 生成中间过渡 |

### 请求参数

<Warning>
  帧转视频请求需要使用 `multipart/form-data` 格式（不是 JSON），因为需要上传图片文件。
</Warning>

<ParamField body="prompt" type="string" required>
  视频描述，建议描述画面如何运动（如「镜头缓慢推进」「人物向前走」）
</ParamField>

<ParamField body="model" type="string" required>
  必须使用 `-fl` 后缀的模型，如 `veo-3.1-fl`、`veo-3.1-landscape-fl` 等
</ParamField>

<ParamField body="input_reference" type="file" required>
  图片文件。传 1 次为首帧模式，传 2 次为首尾帧模式
</ParamField>

### 首帧模式示例（单图）

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

<CodeGroup>
  ```bash cURL theme={null}
  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"'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript (Node.js) theme={null}
  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);
  ```
</CodeGroup>

### 首尾帧模式示例（双图）

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

<CodeGroup>
  ```bash cURL theme={null}
  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"'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript (Node.js) theme={null}
  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);
  ```
</CodeGroup>

### 响应与后续处理

帧转视频的响应格式与文生视频相同，返回 `video_id` 后需要轮询获取结果：

```json theme={null}
{
  "id": "video_xyz789",
  "object": "video",
  "created": 1762181811,
  "status": "queued",
  "model": "veo-3.1-landscape-fl"
}
```

后续流程请参考上方的[完整调用流程](#完整调用流程)章节。

### 使用建议

<CardGroup cols={2}>
  <Card title="首帧模式适用场景" icon="play">
    * 让静态图片「动起来」
    * 产品展示动画
    * 人物照片生成动态视频
  </Card>

  <Card title="首尾帧模式适用场景" icon="arrow-right-left">
    * 场景转换（白天→夜晚、四季变化）
    * 表情变化动画
    * 物体变形过渡
  </Card>
</CardGroup>

<Tip>
  **提示词技巧**：使用帧转视频时，prompt 应描述「画面如何运动」而非「画面内容」。例如：「镜头缓慢推进」「人物转头微笑」「花朵逐渐绽放」。
</Tip>

## 错误处理

| 错误码               | 说明       | 解决方案              |
| ----------------- | -------- | ----------------- |
| `invalid_api_key` | API 密钥无效 | 检查 API 密钥是否正确     |
| `invalid_model`   | 模型不存在    | 使用支持的模型名称         |
| `invalid_prompt`  | 提示词无效    | 检查提示词长度和内容        |
| `video_not_found` | 视频任务不存在  | 检查 video\_id 是否正确 |
| `video_not_ready` | 视频尚未生成完成 | 继续轮询任务状态          |
| `quota_exceeded`  | 配额超限     | 联系客服增加配额          |

**错误响应格式**

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "type": "authentication_error"
  }
}
```

## 常见问题

<Accordion title="如何选择合适的模型？">
  * **性价比优先**：选择 `-fast` 系列（\$0.15/视频）
  * **质量优先**：选择标准系列（\$0.25/视频）
  * **需要图片转视频**：选择 `-fl` 系列
  * **横屏内容**：选择 `-landscape` 系列
</Accordion>

<Accordion title="视频生成需要多长时间？">
  * **快速模型** (`-fast`)：约 30-60 秒
  * **标准模型**：约 1-2 分钟

  建议轮询间隔设置为 5-10 秒。
</Accordion>

<Accordion title="视频 URL 有效期多久？">
  视频 URL 有效期通常为 24 小时，建议生成成功后及时下载保存。
</Accordion>

<Accordion title="批量使用有优惠吗？">
  大批量使用可联系客服获取企业优惠，邮箱：`feedback@apiyi.com`
</Accordion>

## 技术规格速查表

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