> ## 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.

# VEO 3.1 视频生成

> Google VEO 3.1 官逆通道完整指南：声画同步视频生成、固定 8 秒时长、支持首尾帧（Frame-to-Video）、HD 横/竖屏，4K 高清版本陆续上线。

## 概述

**VEO 3.1** 是谷歌当下最强的 AI 视频生成模型系列，**原生声画同步生成**：根据文本提示词或参考图片输出固定 8 秒短片，自带同步音轨。API易 通过 **官逆通道**（Reverse-engineered）接入 Google Flow，按次计费、支持同步流式与异步任务两种调用方式。

<Note>
  **🎬 核心亮点**：声画同步原生输出 + 固定 8 秒短片 + 首尾帧（Frame-to-Video）创作 + HD 横竖屏 + **价格远低于官方**（\$0.15 起）+ 同步流式可见进度。**适合短视频、广告片段、产品演示、社交媒体素材** 等高节奏生产场景。
</Note>

<CardGroup cols={2}>
  <Card title="同步调用 API" icon="bolt" href="/api-capabilities/veo/quick-start">
    `POST /v1/chat/completions`，复用 OpenAI Chat Completions 协议，支持 `stream: true` 实时进度。
  </Card>

  <Card title="异步调用 API" icon="hourglass" href="/api-capabilities/veo/async-api">
    `POST /v1/videos` 三步异步流程，支持文生视频与首尾帧上传，便于批量管理。
  </Card>
</CardGroup>

## 为什么选 API易 的 VEO 3.1

VEO 3.1 是 **官逆通道**（透传 Google Flow 服务），针对企业生产场景在 **价格**、**接入门槛**、**功能完整度** 三方面做了深度优化：

<CardGroup cols={2}>
  <Card title="价格屠夫 · 远低于官方" icon="badge-dollar-sign">
    \$0.15 起 / 8 秒视频，**对比谷歌官方立省 80%+**。无需开通 Google Cloud / Vertex AI 账号，按次计费成本透明。
  </Card>

  <Card title="不限并发 · 企业可放量" icon="infinity">
    平台维护账号池透明聚合，批量出片 / 短视频矩阵 / 广告生产场景下可线性扩容，**无谷歌账号 Tier 限制**。
  </Card>

  <Card title="同价 + 充值最高加赠" icon="percent">
    叠加 [充值加赠活动](/faq/recharge-promotions) 实际成本进一步下降。**生成失败不计费**，按成功结果结算。
  </Card>

  <Card title="全球零门槛接入" icon="globe">
    **无需海外服务器或代理**，国内机房、家宽网络、海外节点均可直连 `api.apiyi.com`，省去为 Google Flow 配置出海链路的麻烦。
  </Card>

  <Card title="OpenAI 兼容 · 双模式接入" icon="plug">
    同步走 `/v1/chat/completions`（与对话模型一致），异步走 `/v1/videos`（OpenAI Video API 风格）。两种协议都和你已有的 SDK / 工程代码无缝复用。
  </Card>

  <Card title="专业服务 · 企业陪跑" icon="handshake">
    团队深耕视频生成场景，在 prompt 工程、首尾帧素材准备、批量生产、视频后处理等环节具备丰富经验，可为企业客户提供从 PoC 到生产上线的完整技术支持。
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="声画同步原生输出" icon="volume-2">
    VEO 3.1 在视频生成的同时**原生输出同步音轨**（环境音、对话、配乐），无需后期单独配音。
  </Card>

  <Card title="生成速度领先" icon="bolt">
    `-fast` 系列 30–60 秒出片、标准系列 1–2 分钟，**生成速度比 Sora 2 快 50%**，适合高节奏内容生产。
  </Card>

  <Card title="首尾帧创作（Frame-to-Video）" icon="images">
    `-fl` 后缀模型支持上传 1 张（首帧）或 2 张（首尾帧）参考图，让静态画面动起来，或在两个画面间自动生成过渡动画。
  </Card>

  <Card title="横竖屏自由切换" icon="smartphone">
    竖屏 720×1280（社媒短视频）、横屏 1280×720（广告 / 演示），通过模型名 `-landscape` 后缀切换。
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="同步流式进度回显" icon="chart-line">
    同步模式（`/v1/chat/completions` + `stream: true`）实时返回 `> 🏃 进度：XX%` 文本片段，前端可直接展示生成进度条。
  </Card>

  <Card title="异步任务化" icon="list-check">
    异步模式返回 `video_id`，独立轮询和下载，适合批量管理、断点续传、长任务后台跑。
  </Card>

  <Card title="按成功结果计费" icon="circle-check">
    生成失败 / 内容审核拦截 / 服务过载等错误均**不计费**，只为最终拿到的视频付费。
  </Card>

  <Card title="多视频并行（n 参数）" icon="layers">
    同步模式 `n` 参数最多一次出 4 条不同视频（同 prompt 多结果），便于内容多样性挑选。
  </Card>
</CardGroup>

## 模型定价

按 **次** 计费（每条 8 秒视频固定单价），**仅对成功生成的视频收费**，失败任务不计费。

### HD 系列（720p，已上线）

| 模型名                         | 描述            | 分辨率      | 单价     |
| --------------------------- | ------------- | -------- | ------ |
| `veo-3.1`                   | 默认竖屏          | 720×1280 | \$0.25 |
| `veo-3.1-fl`                | 竖屏 + 首尾帧      | 720×1280 | \$0.25 |
| `veo-3.1-fast`              | 竖屏 + 快速       | 720×1280 | \$0.15 |
| `veo-3.1-fast-fl`           | 竖屏 + 快速 + 首尾帧 | 720×1280 | \$0.15 |
| `veo-3.1-landscape`         | 横屏            | 1280×720 | \$0.25 |
| `veo-3.1-landscape-fl`      | 横屏 + 首尾帧      | 1280×720 | \$0.25 |
| `veo-3.1-landscape-fast`    | 横屏 + 快速       | 1280×720 | \$0.15 |
| `veo-3.1-landscape-fast-fl` | 横屏 + 快速 + 首尾帧 | 1280×720 | \$0.15 |

### 4K 高清系列（即将上线）

<Info>
  **4K 高清版本陆续上线中**，模型变体覆盖竖屏 / 横屏 / 快速 / 首尾帧组合，命名延续 HD 系列规则。**单价信息将在官方放量后补充至本表**，企业批量需求可联系商务提前对接试用。
</Info>

<Info>
  **计费说明**：

  * **按次计费**：每条 8 秒视频固定单价，与 prompt 长度、是否传参考图、`n` 参数无关（n=2 即按 2 条结算）
  * **失败不扣费**：任务进入 `failed` / 内容审核拦截 / 网关错误时**不计费**，可放心重试
  * **充值加赠**：详见 [充值加赠活动](/faq/recharge-promotions)
</Info>

## 技术规格

| 维度                      | 规格                                        |
| ----------------------- | ----------------------------------------- |
| **模型基名**                | `veo-3.1`（HD）/ 4K 系列待补充                   |
| **变体维度**                | 朝向（竖/横）× 速度档（标准/快）× 创作模式（文生 / 首尾帧 `-fl`）  |
| **视频时长**                | 固定 **8 秒**（不可调）                           |
| **HD 分辨率**              | 竖屏 720×1280、横屏 1280×720                   |
| **4K 分辨率**              | 即将上线，规格待补充                                |
| **音轨**                  | ✅ 声画同步，自带原生音轨                             |
| **首尾帧（Frame-to-Video）** | ✅ `-fl` 后缀模型；首帧 1 张或首尾帧 2 张               |
| **同步生成耗时**              | `-fast` 系列 30–60 秒，标准系列 1–2 分钟            |
| **同步进度回显**              | ✅ `/v1/chat/completions` + `stream: true` |
| **异步轮询**                | ✅ `/v1/videos` + 任务 ID + `/content` 下载    |
| **`n` 参数**              | 同步模式最多 4 条 / 次（异步模式建议 1）                  |
| **视频 URL 有效期**          | 24 小时                                     |

## 端点一览

| 端点                              | 方法   | 用途                    | Content-Type                               |
| ------------------------------- | ---- | --------------------- | ------------------------------------------ |
| `/v1/chat/completions`          | POST | **同步流式**生成（推荐实时交互场景）  | `application/json`                         |
| `/v1/videos`                    | POST | **异步任务**：提交文生视频或首尾帧任务 | `application/json` 或 `multipart/form-data` |
| `/v1/videos/{video_id}`         | GET  | 异步轮询任务状态              | —                                          |
| `/v1/videos/{video_id}/content` | GET  | 异步下载视频 URL            | —                                          |

<Tip>
  **域名选择**：主域名 `api.apiyi.com`，也可使用 `vip.apiyi.com` / `b.apiyi.com` 等其它网关域名，响应行为一致。
</Tip>

## 接入准备

### 令牌分组

VEO 3.1 走 API易 **默认分组（default）** 即可调用，**无需切换或申请独立分组**。在控制台「令牌管理」新建一个默认分组的令牌，计费类型选「**按量优先**」或「**按次计费**」均可直接调用。

### 在线测试工具：iCover AI

如果想在写代码前先快速试出效果，可以使用 API易 旗下的视频生成测试站 **iCover AI**：

* 测试地址：`icover.ai/zh/veo`
* 接入方式：填入一个**默认分组**的令牌（按量优先 / 按次计费均可），即可直接体验文生视频与首尾帧创作
* 工具背景：iCover AI 是 API易（APIYI）官方运营的 AI 视频生成测试工具，与生产 API 共用同一套服务，**测试效果即代表正式调用效果**

<Tip>
  调试阶段建议先在 iCover AI 跑通 prompt，再迁移到自己的代码里走 [同步调用](/api-capabilities/veo/quick-start) 或 [异步调用](/api-capabilities/veo/async-api) 接入。
</Tip>

## 关键参数详解

### 模型变体命名规则

VEO 3.1 通过模型名后缀组合切换功能，**不通过单独参数控制**：

| 后缀           | 作用              | 默认                |
| ------------ | --------------- | ----------------- |
| `-landscape` | 横屏（1280×720）    | 不带 = 竖屏（720×1280） |
| `-fast`      | 快速档（速度优先，价格更低）  | 不带 = 标准档          |
| `-fl`        | 首尾帧创作（必须搭配上传图片） | 不带 = 纯文生视频        |

**组合示例**：

* `veo-3.1` —— 标准竖屏文生视频（默认）
* `veo-3.1-landscape-fast` —— 快速横屏文生视频（性价比首选）
* `veo-3.1-landscape-fl` —— 标准横屏首尾帧创作
* `veo-3.1-landscape-fast-fl` —— 快速横屏首尾帧创作（成本最低的图生视频）

<Warning>
  - **`-fl` 模型必须传 `input_reference` 图片**，否则报错；纯文生视频不要带 `-fl` 后缀
  - 异步首尾帧请求必须走 `multipart/form-data`（不是 JSON），上传 1 张为首帧、2 张为首尾帧
  - 4 种维度组合后共 8 个 HD 模型 ID，**字符顺序固定**：`landscape` → `fast` → `fl`
</Warning>

### `n`（一次出几条视频，同步模式）

* 范围：`1` \~ `4`，默认 `1`
* 仅同步模式（`/v1/chat/completions`）支持，异步模式 `n` 不生效
* **按视频条数计费**（n=2 即按 2 条结算）

## 最佳实践

<Steps>
  <Step title="先用 -fast 验证 prompt">
    每个新 prompt 先用 `veo-3.1-fast` 或 `veo-3.1-landscape-fast` 跑一条试水（成本 \$0.15，30–60 秒出片），定型后再切到标准档拿最佳画质。
  </Step>

  <Step title="按场景选朝向">
    * **社媒短视频 / 抖音 / 小红书** → 竖屏（默认无 `-landscape`）
    * **YouTube / 广告 / 产品演示** → 横屏（`-landscape`）
  </Step>

  <Step title="同步 vs 异步按需选">
    * 需要**实时进度反馈**给用户 → 同步流式（`/v1/chat/completions` + `stream: true`）
    * **批量后台跑**或长任务 → 异步任务化（`/v1/videos` + 轮询）
    * 详见 [同步调用](/api-capabilities/veo/quick-start) / [异步调用](/api-capabilities/veo/async-api)
  </Step>

  <Step title="首尾帧创作聚焦「动作」">
    `-fl` 模型已经定了画面（首帧或首尾帧），prompt 应聚焦**如何让画面动起来**：镜头推拉、物体运动、光线变化、人物表情，例：`"镜头缓慢推进，叶子轻摇，阳光透过树叶闪烁"`。
  </Step>

  <Step title="首尾帧场景搭配「渐变叙事」">
    首尾帧最强场景是**两个画面间的自然过渡**（白天→夜晚、四季变化、表情变化、物体变形），prompt 描述过渡过程、动作变化即可，无需描述细节。
  </Step>

  <Step title="客户端超时 ≥ 2 分钟">
    同步流式调用整个连接会保持到生成完成（`-fast` ≈ 60 秒，标准 ≈ 2 分钟），客户端超时建议 ≥ **120 秒**。异步模式 POST 提交是秒级，但建议 30 秒打底。
  </Step>

  <Step title="生成视频立即下载">
    视频 URL 有效期**仅 24 小时**，生产场景务必拿到 `completed` 后立即下载并落地到自己的 OSS / CDN，避免链接过期。
  </Step>

  <Step title="同时跑多任务用 n 或多次提交">
    * 同 prompt 出多个变体 → 用 `n: 4` 一次拿 4 条
    * 不同 prompt 批量跑 → 多次异步 POST 各拿独立 `video_id`，再独立轮询
  </Step>
</Steps>

## 错误码与重试

| 状态码                       | 含义                               | 处理建议                                  |
| ------------------------- | -------------------------------- | ------------------------------------- |
| `400`                     | 参数非法（model 不存在、`-fl` 缺图、`n` 越界等） | 校验参数；首尾帧请求务必走 multipart 上传            |
| `401` / `invalid_api_key` | API Key 无效                       | 检查 Bearer Token；确认控制台分组配置             |
| `403`                     | 内容审核拦截                           | 调整 prompt；参考图避免敏感内容                   |
| `429` / `quota_exceeded`  | 限流 / 配额超限 / 余额不足                 | 指数退避重试；超出默认配额联系商务申请扩容                 |
| `5xx`                     | 网关 / 上游错误                        | 异步任务重试 1–2 次（不计费）                     |
| 任务 `failed`               | 视频生成失败（多为内容审核或上游容量）              | 见下方「内容审核错误」小节，调整 prompt 重试；**该任务不计费** |
| `video_not_found`         | video\_id 不存在或已过期                | 确认 ID 正确；24 小时内查询                     |

### 内容审核错误（`PUBLIC_` 前缀）

凡是 `error.message` / `fail_reason` 字段以 **`PUBLIC_` 开头** 的失败任务，均为**上游官方的内容策略拦截**——意味着 prompt、参考图或生成结果触发了 Google Flow 的内容审核，与 API易 通道无关。**这类任务不计费**，调整后可直接重试。

| 错误码                                           | 含义                                 |
| --------------------------------------------- | ---------------------------------- |
| `PUBLIC_ERROR_AUDIO_FILTERED`                 | 音轨被过滤（多见于敏感语句、特定语言对白、版权音频）         |
| `PUBLIC_ERROR_PROMINENT_PEOPLE_FILTER_FAILED` | 命中名人 / 公众人物过滤（prompt 或参考图涉及真实知名人物） |
| 其它 `PUBLIC_ERROR_*`                           | 同属上游官方内容策略拦截，按字段名定位触发原因            |

**处理建议：**

1. **重写 prompt**：去除人名、品牌、敏感词；如有对白，改为通用描述（例如「角色用平静语气说话」）
2. **替换参考图**：避免使用真实人物（特别是名人）作为首尾帧
3. **重试不计费**：该类任务平台**不扣额度**，可放心调整后重试

**典型失败任务 JSON 示例：**

```json theme={null}
{
  "task_id": "video_693742f8-45c9-4608-85e0-1c4b3dea97eb",
  "object": "task",
  "task_type": "sora2_video_generation",
  "model_name": "veo-3.1-fl",
  "platform": "openai",
  "status": "failed",
  "progress": "100%",
  "fail_reason": "PUBLIC_ERROR_AUDIO_FILTERED",
  "error": {
    "message": "PUBLIC_ERROR_AUDIO_FILTERED",
    "type": "task_failed"
  },
  "data": {
    "id": "video_693742f8-45c9-4608-85e0-1c4b3dea97eb",
    "object": "video",
    "model": "veo-3.1-fl",
    "size": "720x1280",
    "status": "failed",
    "error": {
      "code": "",
      "message": "PUBLIC_ERROR_AUDIO_FILTERED"
    }
  }
}
```

<Info>
  **建议客户端**：

  * 同步请求超时 **120 秒**起步（标准档）；`-fast` 可降到 **60 秒**
  * 异步 POST 提交超时 **30 秒**；GET 轮询间隔 **5–10 秒**，最长等待 **10 分钟**
  * 对 5xx 与任务 `failed` 做 **指数退避重试**（建议 2 次）
  * 记录响应头 `x-request-id` 方便排查
</Info>

## 常见问题

<AccordionGroup>
  <Accordion title="VEO 3.1 是官转还是官逆？现在能用官转吗？">
    **官逆**。VEO 3.1 通过 API易 维护的 Google Flow 账号池透明转发，价格远低于谷歌官方 Veo Studio 价格，按次计费、支持失败不计费。**目前暂无官转通道**——谷歌官方 Vertex AI Veo API 上线后我们会评估接入，届时本页会同步更新。
  </Accordion>

  <Accordion title="VEO 3.1 vs Sora 2，应该选哪个？">
    | 维度       | VEO 3.1                 | Sora 2（官转）                 |
    | -------- | ----------------------- | -------------------------- |
    | **价格**   | \$0.15–\$0.25 / 8 秒（按次） | \$0.40–\$8.40 / 4–12 秒（按秒） |
    | **时长**   | 固定 8 秒                  | 4 / 8 / 12 秒               |
    | **生成速度** | 30 秒 – 2 分钟             | 3–10 分钟                    |
    | **音轨**   | ✅ 声画同步原生                | ✅ 声画同步原生                   |
    | **首尾帧**  | ✅ `-fl` 系列              | ✅ `input_reference` 单图     |
    | **稳定性**  | 官逆，受风控影响                | 官转 99.99%                  |
    | **分辨率**  | 720p（4K 即将上线）           | 720p / 1024p / 1080p       |

    **快、便宜、批量场景选 VEO；高画质、稳定性优先选 Sora 2 Pro。** 详见 [Sora 2 概览](/api-capabilities/sora-2/overview)。
  </Accordion>

  <Accordion title="为什么视频时长固定 8 秒？能延长吗？">
    Google Flow 上游本身只开放 8 秒固定时长，目前**没有调整时长的参数**。如需更长视频，建议**首尾帧拼接**：用 `-fl` 模型生成多个 8 秒片段，最后片段的尾帧作为下个片段的首帧，再用 ffmpeg 拼接为长视频。
  </Accordion>

  <Accordion title="如何选标准档 vs -fast 档？">
    * **要最高画质 / 关键素材** → 标准档（`veo-3.1` / `veo-3.1-landscape`），\$0.25 / 条
    * **量产 / 试错 / 内部预览** → fast 档（`-fast` 后缀），\$0.15 / 条，速度更快
    * **`-fast` 与标准档画质差距不大**，多数生产场景 fast 档已够用
  </Accordion>

  <Accordion title="首尾帧（-fl）模型怎么用？">
    `-fl` 系列必须搭配 `input_reference` 上传图片：

    * **传 1 张** → 首帧模式：以图片作为视频开头，AI 自动续编后续画面
    * **传 2 张** → 首尾帧模式：第一张为开头、第二张为结尾，AI 生成中间过渡

    必须走 multipart/form-data（不是 JSON）。详见 [异步调用 - 帧转视频](/api-capabilities/veo/async-api#帧转视频模式)。
  </Accordion>

  <Accordion title="生成失败会扣费吗？">
    **不会**。VEO 3.1 按**成功结果**计费：任务进入 `failed`、内容审核拦截、网关 5xx 错误、参数错误等情况都不计费。**只有视频真正生成完成（拿到 URL）才按次扣费**。
  </Accordion>

  <Accordion title="视频 URL 多久过期？">
    **24 小时**。视频生成完成后请立即下载到自己的 OSS / CDN 持久化，避免链接过期后无法访问。
  </Accordion>

  <Accordion title="同步流式调用怎么读进度？">
    `/v1/chat/completions` + `stream: true` 模式下，响应是 SSE 格式，每个 chunk 含进度文本：

    ```text theme={null}
    data: {"choices":[{"delta":{"content":"> 🏃 进度：45.0%\n\n"}}]}
    ...
    data: {"choices":[{"delta":{"content":"> ✅ 第1个视频生成成功，[点击这里](https://.../xxx.mp4) 查看视频~~~\n\n"}}]}
    data: [DONE]
    ```

    前端只需解析 `delta.content` 里的"进度"和视频 URL 即可。完整示例见 [同步调用](/api-capabilities/veo/quick-start#流式响应说明)。
  </Accordion>

  <Accordion title="支持哪些图片格式？参考图大小限制？">
    `-fl` 模型的 `input_reference` 接受 `jpeg` / `png`，建议单张图 ≤ 5 MB。**没有强制分辨率要求**（不同于 Sora 2），但**图片比例最好与目标视频朝向一致**：竖屏视频用竖图、横屏用横图，否则 AI 会自动裁切。
  </Accordion>

  <Accordion title="可以用 OpenAI 官方 SDK 调用吗？">
    可以。**同步模式**完全兼容 OpenAI Chat Completions：

    ```python theme={null}
    from openai import OpenAI
    client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1")
    resp = client.chat.completions.create(
        model="veo-3.1-fast",
        messages=[{"role": "user", "content": "画只猫在天上飞"}],
        stream=True,
        n=1
    )
    for chunk in resp:
        print(chunk.choices[0].delta.content or "", end="")
    ```

    **异步模式** 用 `client.videos.create()` 也可以，但首尾帧场景必须走原生 requests 多文件上传（OpenAI SDK 默认只支持单文件）。
  </Accordion>

  <Accordion title="可以同时跑多个任务吗？速率限制是多少？">
    可以。每次 POST `/v1/videos` 返回独立 `video_id`，多任务并发提交、独立轮询。**默认配额已能满足大多数业务**，企业批量需求（>10 并发、单日 >100 条）请联系商务申请独立资源池。
  </Accordion>

  <Accordion title="主动取消生成中的任务可以吗？">
    **不支持**。当前没有 cancel 端点，任务一旦提交会跑完。建议先用 `-fast` 跑试 prompt，确认风格再切到标准档，避免长任务跑废。
  </Accordion>

  <Accordion title="可以禁用音轨吗？">
    **目前不支持**。VEO 3.1 默认输出带同步音轨的视频，官方未开放禁用音轨的参数。如需纯视频，下载后用 ffmpeg `-an` 剥离即可：`ffmpeg -i input.mp4 -an output.mp4`。
  </Accordion>

  <Accordion title="4K 版本什么时候上线？价格大概多少？">
    4K 系列正在灰度放量中，模型变体延续 HD 命名规则（覆盖竖横、快慢、首尾帧组合）。**最终单价以本页定价表正式更新为准**，企业批量需求可联系商务提前对接试用资源。
  </Accordion>
</AccordionGroup>

## 相关文档

* [同步调用 API](/api-capabilities/veo/quick-start) - `/v1/chat/completions` + `stream: true` 实时流式调用，文生视频 + 首尾帧示例
* [异步调用 API](/api-capabilities/veo/async-api) - `/v1/videos` 三步异步流程、首尾帧上传、Python 完整客户端示例
* [Sora 2 视频生成](/api-capabilities/sora-2/overview) - OpenAI 官转通道对照
* [充值加赠活动](/faq/recharge-promotions) - 加赠最高档位与适用渠道
* [API 使用手册](/api-manual) - 通用调用规范、超时与重试建议
* 谷歌官方 Veo 介绍：`deepmind.google/technologies/veo/`

<Info>
  VEO 3.1 是 API易 通过 Google Flow 官逆通道实现的高性价比视频生成服务，**生成速度领先、价格远低于官方**。两种调用模式（同步流式、异步任务化）按场景选择，与你已有的 OpenAI SDK / 工程代码无缝对接。如有问题或建议，欢迎在控制台工单中反馈。
</Info>