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

# 异步调用 API

> Veo-3.1 异步视频生成 API，更稳定的任务队列方式

**异步端点：** `https://api.yelinai.com/v1/videos`**调用方式：** 三步骤（创建任务 → 查询状态 → 获取视频）**优势：** 更稳定 | 任务队列 | 支持长时任务 | 失败不扣费

## 为什么选择异步 API？

## 更高稳定性

基于任务队列，避免长连接超时问题

## 失败不扣费 ⭐

**重大优势**：任何原因失败都不扣费

* ✓ 内容违规 → 不扣费
* ✓ 队列超时 → 不扣费
* ✓ 生成失败 → 不扣费

同步API只要请求成功（HTTP 200）就扣费，即使最终生成失败！

## 灵活轮询

可随时查询任务状态和进度

## 批量处理

适合批量生成、后台任务处理

## 同步 vs 异步对比

| 特性       | 同步 API                 | 异步 API（推荐）      |
| -------- | ---------------------- | --------------- |
| **调用方式** | 单次请求等待完成               | 创建任务后轮询查询       |
| **端点**   | `/v1/chat/completions` | `/v1/videos`    |
| **模型选择** | 通过 model 参数指定画幅        | 通过 model 参数指定画幅 |
| **图生视频** | 支持图片URL和Base64         | 支持图片URL         |
| **失败扣费** | 请求成功但生成失败会扣费           | ⭐ 失败不扣费         |
| **稳定性**  | 依赖长连接                  | ⭐⭐⭐⭐⭐ 更稳定       |
| **进度查看** | 流式输出                   | 轮询查询进度百分比       |
| **超时处理** | 需要设置长超时                | 任务独立运行，无超时限制    |
| **适用场景** | 快速测试、实时反馈              | 生产环境、批量生成       |

**推荐使用异步 API**，特别是在生产环境或需要批量生成视频时，稳定性更有保障。

## 快速开始

异步调用分为三个步骤：

1

创建视频任务

POST 请求创建任务，获取任务 ID

2

查询任务状态

定期轮询查询生成进度

3

下载视频

任务完成后获取视频文件

### 完整示例

步骤1: 创建任务（文生视频）

步骤1: 创建任务（图生视频 - 单图）

步骤1: 创建任务（图生视频 - 首尾帧）

步骤2: 查询状态

步骤3: 获取视频

```
curl -X POST "https://api.yelinai.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1",
    "prompt": "一只可爱的猫咪在阳光明媚的花园里玩球"
  }'

# 响应示例
{
  "id": "video_abc123",
  "object": "video",
  "created": 1762181811,
  "status": "queued",
  "model": "veo-3.1"
}
```

## API 端点详解

### 1. 创建视频任务

**POST** `https://api.yelinai.com/v1/videos`创建一个新的视频生成任务

#### 请求参数

| 参数                | 类型     | 必需 | 说明                                              |
| ----------------- | ------ | -- | ----------------------------------------------- |
| `model`           | string | ✓  | 模型名称（见下方模型列表）                                   |
| `prompt`          | string | ✓  | 视频生成提示词                                         |
| `input_reference` | file   | ❌  | 图片文件，支持 1-2 张（2张时为首尾帧模式，multipart/form-data 格式） |

#### 可用模型

| 模型名称                        | 画幅 | 速度 | 图生视频 | 价格       |
| --------------------------- | -- | -- | ---- | -------- |
| `veo-3.1`                   | 竖屏 | 标准 | ❌    | \$0.25/次 |
| `veo-3.1-fl`                | 竖屏 | 标准 | ✅    | \$0.25/次 |
| `veo-3.1-fast`              | 竖屏 | 快速 | ❌    | \$0.15/次 |
| `veo-3.1-fast-fl`           | 竖屏 | 快速 | ✅    | \$0.15/次 |
| `veo-3.1-landscape`         | 横屏 | 标准 | ❌    | \$0.25/次 |
| `veo-3.1-landscape-fl`      | 横屏 | 标准 | ✅    | \$0.25/次 |
| `veo-3.1-landscape-fast`    | 横屏 | 快速 | ❌    | \$0.15/次 |
| `veo-3.1-landscape-fast-fl` | 横屏 | 快速 | ✅    | \$0.15/次 |

**模型命名规则：**

* `landscape` = 横屏（16:9）
* `fast` = 快速版（更便宜）
* `fl` = 支持帧转视频（图生视频）

**首尾帧功能**图生视频模型（带 `-fl` 后缀）支持传入 2 张图片：

* **第一张**：视频开始帧
* **第二张**：视频结束帧

API 会自动生成从开始帧到结束帧的平滑过渡动画。

#### 响应字段

| 字段        | 类型      | 说明              |
| --------- | ------- | --------------- |
| `id`      | string  | 任务唯一标识，用于后续查询   |
| `object`  | string  | 固定为 `"video"`   |
| `model`   | string  | 使用的模型           |
| `status`  | string  | 任务状态：`"queued"` |
| `created` | integer | 创建时间戳           |

### 2. 查询任务状态

**GET** `https://api.yelinai.com/v1/videos/{video_id}`查询视频生成任务的当前状态

#### 路径参数

| 参数         | 类型     | 必需 | 说明            |
| ---------- | ------ | -- | ------------- |
| `video_id` | string | ✓  | 创建任务时返回的任务 ID |

#### 响应字段

| 字段        | 类型      | 说明            |
| --------- | ------- | ------------- |
| `id`      | string  | 任务 ID         |
| `object`  | string  | 固定为 `"video"` |
| `model`   | string  | 使用的模型         |
| `status`  | string  | 任务状态（见下方说明）   |
| `prompt`  | string  | 原始提示词         |
| `created` | integer | 创建时间戳         |

#### 任务状态说明

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

### 3. 获取视频内容

**GET** `https://api.yelinai.com/v1/videos/{video_id}/content`获取已完成视频的实际内容

#### 路径参数

| 参数         | 类型     | 必需 | 说明    |
| ---------- | ------ | -- | ----- |
| `video_id` | string | ✓  | 任务 ID |

#### 响应字段

| 字段           | 类型      | 说明            |
| ------------ | ------- | ------------- |
| `id`         | string  | 任务 ID         |
| `object`     | string  | 固定为 `"video"` |
| `status`     | string  | 任务状态          |
| `model`      | string  | 使用的模型         |
| `prompt`     | string  | 原始提示词         |
| `url`        | string  | 视频下载 URL      |
| `duration`   | integer | 视频时长（秒）       |
| `resolution` | string  | 视频分辨率         |
| `created`    | integer | 创建时间戳         |

**重要提示**视频 URL 有效期通常为 **24 小时**，请及时下载保存到本地！

## 完整代码示例

### Python 示例（含轮询逻辑）

```
import requests
import time
import os

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.yelinai.com/v1"

# 步骤1: 创建视频任务
def create_video_task(prompt, model="veo-3.1", image_paths=None):
    """创建视频生成任务

    Args:
        prompt: 视频生成提示词
        model: 模型名称
        image_paths: 图片路径，可以是：
            - None: 文生视频
            - str: 单张图片路径
            - list: 多张图片路径（首尾帧模式，最多2张）
    """
    url = f"{BASE_URL}/videos"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    if image_paths:
        # 统一转为列表处理
        if isinstance(image_paths, str):
            image_paths = [image_paths]

        # 图生视频：使用 multipart/form-data 上传图片
        files = []
        for path in image_paths:
            if not os.path.exists(path):
                raise FileNotFoundError(f"图片文件不存在: {path}")
            files.append(("input_reference", (os.path.basename(path), open(path, 'rb'), "image/jpeg")))

        data = {"model": model, "prompt": prompt}
        response = requests.post(url, headers=headers, files=files, data=data)

        # 关闭文件句柄
        for _, (_, f, _) in files:
            f.close()
    else:
        # 文生视频：使用 JSON 格式
        headers["Content-Type"] = "application/json"
        data = {"model": model, "prompt": prompt}
        response = requests.post(url, headers=headers, json=data)

    response.raise_for_status()
    return response.json()

# 步骤2: 轮询查询状态
def wait_for_video(video_id, poll_interval=5, timeout=600):
    """等待视频生成完成"""
    url = f"{BASE_URL}/videos/{video_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    start_time = time.time()

    while True:
        # 检查超时
        if time.time() - start_time > timeout:
            raise TimeoutError(f"视频生成超时（{timeout}秒）")

        # 查询状态
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        task = response.json()

        status = task["status"]
        print(f"状态: {status}")

        if status == "completed":
            return task
        elif status == "failed":
            raise Exception(f"生成失败")

        # 等待后重试
        time.sleep(poll_interval)

# 步骤3: 获取视频内容
def get_video_content(video_id):
    """获取视频内容和URL"""
    url = f"{BASE_URL}/videos/{video_id}/content"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

# 步骤4: 下载视频
def download_video(video_url, save_path="video.mp4"):
    """下载视频文件"""
    response = requests.get(video_url, stream=True)
    response.raise_for_status()

    with open(save_path, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                f.write(chunk)

    print(f"视频已保存到: {save_path}")

# 完整流程
def generate_video_async(prompt, model="veo-3.1"):
    """异步生成视频的完整流程"""
    print("1. 创建视频任务...")
    task = create_video_task(prompt, model)
    video_id = task["id"]
    print(f"   任务ID: {video_id}")

    print("\n2. 等待视频生成...")
    completed_task = wait_for_video(video_id)
    print("   生成完成！")

    print("\n3. 获取视频内容...")
    content = get_video_content(video_id)
    video_url = content["url"]
    print(f"   视频URL: {video_url}")

    print("\n4. 下载视频...")
    download_video(video_url)
    print("\n✅ 完成！")

# 使用示例
if __name__ == "__main__":
    # 文生视频 - 竖屏标准版
    # 文生视频 - 竖屏标准版
    generate_video_async(
        prompt="一只可爱的猫咪在阳光明媚的花园里玩球",
        model="veo-3.1"
    )

    # 图生视频 - 单图模式
    # task = create_video_task(
    #     prompt="让这只猫咪慢慢眨眼睛",
    #     model="veo-3.1-fl",
    #     image_paths="test.jpg"
    # )

    # 图生视频 - 首尾帧模式（传入2张图片）
    # 第一张图作为开始帧，第二张图作为结束帧
    # task = create_video_task(
    #     prompt="让画面从开始帧平滑过渡到结束帧，加入动态效果",
    #     model="veo-3.1-landscape-fl",
    #     image_paths=["start_frame.jpg", "end_frame.jpg"]
    # )

    # 文生视频 - 横屏快速版
    # generate_video_async(
    #     prompt="日落时分，海浪轻轻拍打沙滩",
    #     model="veo-3.1-landscape-fast"
    # )
```

### JavaScript/Node.js 示例

```
const axios = require('axios');
const fs = require('fs');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.yelinai.com/v1';

// 创建视频任务
async function createVideoTask(prompt, model = 'veo-3.1') {
  const response = await axios.post(`\`$\{BASE_URL}/videos`, {
    model,
    prompt
  }, {
    headers: { 'Authorization': `Bearer \`$\{API_KEY}` }
  });

  return response.data;
}

// 轮询查询状态
async function waitForVideo(videoId, pollInterval = 5000, timeout = 600000) {
  const startTime = Date.now();

  while (true) {
    // 检查超时
    if (Date.now() - startTime > timeout) {
      throw new Error(`视频生成超时（\`$\{timeout/1000}秒）`);
    }

    // 查询状态
    const response = await axios.get(`\`$\{BASE_URL}/videos/\`$\{videoId}`, {
      headers: { 'Authorization': `Bearer \`$\{API_KEY}` }
    });

    const task = response.data;
    const { status } = task;

    console.log(`状态: \`$\{status}`);

    if (status === 'completed') {
      return task;
    } else if (status === 'failed') {
      throw new Error('生成失败');
    }

    // 等待后重试
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
}

// 获取视频内容
async function getVideoContent(videoId) {
  const response = await axios.get(`\`$\{BASE_URL}/videos/\`$\{videoId}/content`, {
    headers: { 'Authorization': `Bearer \`$\{API_KEY}` }
  });

  return response.data;
}

// 下载视频
async function downloadVideo(videoUrl, savePath = 'video.mp4') {
  const response = await axios.get(videoUrl, { responseType: 'stream' });

  const writer = fs.createWriteStream(savePath);
  response.data.pipe(writer);

  return new Promise((resolve, reject) => {
    writer.on('finish', () => {
      console.log(`视频已保存到: \`$\{savePath}`);
      resolve();
    });
    writer.on('error', reject);
  });
}

// 完整流程
async function generateVideoAsync(prompt, model = 'veo-3.1') {
  try {
    console.log('1. 创建视频任务...');
    const task = await createVideoTask(prompt, model);
    const videoId = task.id;
    console.log(`   任务ID: \`$\{videoId}`);

    console.log('\n2. 等待视频生成...');
    await waitForVideo(videoId);
    console.log('   生成完成！');

    console.log('\n3. 获取视频内容...');
    const content = await getVideoContent(videoId);
    const videoUrl = content.url;
    console.log(`   视频URL: \`$\{videoUrl}`);

    console.log('\n4. 下载视频...');
    await downloadVideo(videoUrl);
    console.log('\n✅ 完成！');

  } catch (error) {
    console.error('错误:', error.message);
  }
}

// 使用示例
generateVideoAsync(
  '一只可爱的猫咪在阳光明媚的花园里玩球',
  'veo-3.1'
);
```

## 最佳实践

轮询间隔设置

**推荐轮询间隔：5-10 秒**

```
# 推荐
poll_interval = 5  # 每5秒查询一次

# 不推荐
poll_interval = 1  # 太频繁，浪费请求
poll_interval = 30 # 太慢，用户体验差
```

**原因：**

* 视频生成通常需要 2-5 分钟
* 5-10 秒可以及时反馈进度
* 避免过于频繁的请求

超时处理

**推荐超时设置：10 分钟（600秒）**

```
def wait_for_video(video_id, timeout=600):
    start_time = time.time()

    while True:
        if time.time() - start_time > timeout:
            # 超时后的处理
            print(f"任务 {video_id} 超时，稍后可继续查询")
            break

        # 查询逻辑...
```

**注意：**

* 任务超时不会自动取消
* 可以稍后继续查询同一个 video\_id
* 任务有效期为 24 小时

错误重试策略

**建议重试逻辑：**

```
def create_video_with_retry(prompt, model, max_retries=3):
    for i in range(max_retries):
        try:
            return create_video_task(prompt, model)
        except Exception as e:
            if i < max_retries - 1:
                print(f"创建失败，{5}秒后重试... ({i+1}/{max_retries})")
                time.sleep(5)
            else:
                raise
```

**重试场景：**

* ✓ 网络错误 → 重试
* ✓ 服务繁忙 (503) → 重试
* ✗ 内容违规 → 不要重试，修改提示词
* ✗ 余额不足 → 不要重试，充值后再试

批量生成优化

**并发控制建议：**

```
import concurrent.futures

def batch_generate_videos(prompts, model="veo-3.1", max_workers=5):
    """批量生成视频，控制并发数"""
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        # 创建所有任务
        future_to_prompt = {
            executor.submit(create_video_task, prompt, model): prompt
            for prompt in prompts
        }

        video_ids = []
        for future in concurrent.futures.as_completed(future_to_prompt):
            task = future.result()
            video_ids.append(task['id'])

        # 并发等待所有任务完成
        futures = [executor.submit(wait_for_video, vid) for vid in video_ids]
        results = [f.result() for f in concurrent.futures.as_completed(futures)]

        return results
```

**建议：**

* 创建任务：可以高并发（10-30个）
* 查询状态：建议并发数 ≤ 10
* 下载视频：建议并发数 ≤ 5

## 定价说明

异步 API 与同步 API **价格完全相同**，按次计费。

| 模型类型                | 价格       | 充值100\$优惠价 |
| ------------------- | -------- | ---------- |
| 标准版（veo-3.1 等）      | \$0.25/次 | ≈ ¥1.7/次   |
| 快速版（veo-3.1-fast 等） | \$0.15/次 | ≈ ¥1.0/次   |

**计费规则：**

* ✓ 仅在视频**成功生成**时收费（status = “completed”）
* ✗ 失败、超时、取消**不计费**
* ✗ 内容安全问题失败**也不扣费**（与同步API的重要区别⭐）
* ✗ 查询状态不计费

**异步API的重要优势**：任何原因导致的失败都不会扣费，包括内容安全审核未通过。而同步API只要请求成功就会扣费，即使最终生成失败。

## 常见问题

任务的有效期是多久？

**任务有效期：24 小时**

* 创建任务后，24 小时内可随时查询任务状态
* 视频生成完成后，文件保存 24 小时
* 超过 24 小时后，任务和视频将被自动清理

**建议：**

* 视频生成完成后立即下载
* 不要依赖服务器长期存储

查询时返回 404 是什么原因？

**可能的原因：**

1. **video\_id 错误** - 检查是否复制完整
2. **任务已过期** - 超过 24 小时
3. **网络问题** - 重试请求

**解决方法：**

```
try:
    response = requests.get(f"{BASE_URL}/videos/{video_id}", headers=headers)
    task = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("任务不存在或已过期")
    else:
        raise
```

异步和同步 API 可以混用吗？

**可以混用，完全独立**两个 API 系统完全独立：

* 不同的端点
* 不同的调用方式
* 相同的定价
* 共享同一个 API Key 和余额

**使用建议：**

* 快速测试 → 使用同步 API
* 生产环境 → 使用异步 API（更稳定）
* 批量生成 → 使用异步 API

如何选择合适的模型？

**根据需求选择：**

| 需求       | 推荐模型                                      |
| -------- | ----------------------------------------- |
| 快速测试     | `veo-3.1-fast`                            |
| 标准竖屏视频   | `veo-3.1`                                 |
| 标准横屏视频   | `veo-3.1-landscape`                       |
| 图生视频（竖屏） | `veo-3.1-fl`                              |
| 图生视频（横屏） | `veo-3.1-landscape-fl`                    |
| 批量生成（省钱） | `veo-3.1-fast` 或 `veo-3.1-landscape-fast` |

## 错误处理

### 常见错误码

| HTTP 状态码 | 错误类型                  | 说明         | 处理建议                |
| -------- | --------------------- | ---------- | ------------------- |
| 400      | Bad Request           | 请求参数错误     | 检查参数格式和值            |
| 401      | Unauthorized          | API Key 无效 | 检查 Authorization 头  |
| 402      | Payment Required      | 余额不足       | 充值后重试               |
| 404      | Not Found             | 任务不存在      | 检查 video\_id 或任务已过期 |
| 429      | Too Many Requests     | 请求过于频繁     | 降低轮询频率              |
| 500      | Internal Server Error | 服务器错误      | 稍后重试                |
| 503      | Service Unavailable   | 服务暂时不可用    | 等待后重试               |

### 错误响应格式

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

## 技术支持

## 需要帮助？

如有问题，欢迎联系我们：

* **邮箱：** [threezhang.cn@gmail.com](mailto:threezhang.cn@gmail.com)
* **微信：** Kikivivikids
* **Telegram：** [https://t.me/laozhang\_cn](https://t.me/laozhang_cn)
* **文档：** []()

## 下一步

## 同步 API

查看同步调用方式（OpenAI 兼容）

## 代码示例

查看更多应用示例

## 模型概览

了解 Veo-3.1 模型详情

## 常见问题

查看更多问题解答