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

# Sora 2 视频生成

> OpenAI Sora 2 / Sora 2 Pro 官转视频生成模型完整指南，文生视频 + 图生视频统一异步端点，支持 4 / 8 / 12 秒、720p / 1024p / 1080p 多档分辨率。

## 概述

**Sora 2** 是 OpenAI 推出的旗舰视频生成模型系列，**视频与音频联动生成**：根据文本提示词或参考图片输出 4–12 秒的高保真视频片段，自带同步音轨。API易 通过 **官方透明转发（官转）通道** 直连 OpenAI 官方 `/v1/videos` 端点，请求和响应字段与官方完全一致。

<Note>
  **🎬 核心亮点**：官方 API 透明转发 + 同步音视频生成 + 4 / 8 / 12 秒灵活时长 + 标准（720p）/ 高清（1024p）/ 全高清（1080p，仅 Pro）三档分辨率。**适合广告短片、电商视频素材、社交媒体短视频、产品演示** 等需要稳定画质 + 精准指令遵循的生产场景。
</Note>

<CardGroup cols={2}>
  <Card title="文生视频 API" icon="wand-sparkles" href="/api-capabilities/sora-2/text-to-video">
    `POST /v1/videos`，纯文本提示词生成视频，JSON 请求体，最简单的入口。
  </Card>

  <Card title="图生视频 API" icon="image" href="/api-capabilities/sora-2/image-to-video">
    `POST /v1/videos` + multipart 上传 `input_reference`，让静态图片动起来。
  </Card>

  <Card title="可视化接口测试" icon="flask-conical" href="https://icover.ai/zh/sora-official">
    在 iCover 可视化测试工具里直接调试本接口，无需写代码。
  </Card>

  <Card title="异步任务查询 / 下载" icon="list-checks" href="https://api.apiyi.com/task">
    在 API易后台查看已提交的视频任务、下载视频链接（API 之外的查询入口）。
  </Card>
</CardGroup>

## 为什么选 API易 的 Sora 2 官转

对标 OpenAI 官方通道，针对企业生产场景在 **稳定性**、**接入门槛**、**成本** 三方面做了深度优化：

<CardGroup cols={2}>
  <Card title="官方直连 · 99.99% 可用" icon="shield-check">
    透明转发到 OpenAI 官方 `/v1/videos`，无中间处理、无协议绕行风险。请求和响应行为与官方一致，**无需关心 OpenAI 账号 Tier、风控波动**，企业可放心走生产。
  </Card>

  <Card title="不限并发 · 企业可放量" icon="infinity">
    批量出片、活动短视频、广告素材生产等高并发场景下可线性扩容，不受官方账号 Tier 限制。**默认即可投递，按需扩容**。
  </Card>

  <Card title="同价 + 充值最高加赠" icon="percent">
    默认按秒单价与 OpenAI 官方一致，叠加 [充值加赠活动](/faq/recharge-promotions) 实际成本进一步下降。失败请求不计费。
  </Card>

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

  <Card title="OpenAI 兼容 · 零代码改动" icon="plug">
    端点路径 `/v1/videos` 与 OpenAI 完全一致，OpenAI 官方 SDK 把 `base_url` 指过来即可调用，参数与字段名一一对齐。
  </Card>

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

## 核心特性

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

  <Card title="多分辨率分档" icon="expand">
    `sora-2` 支持 720p（720×1280 / 1280×720）；`sora-2-pro` 额外支持 1024p、1080p 高清档位，最高 1920×1080。
  </Card>

  <Card title="4 / 8 / 12 秒灵活时长" icon="clock">
    按秒计费，按需选择短片长度。8 秒为最常用档位，平衡画质连贯性和成本。
  </Card>

  <Card title="精准指令遵循" icon="target">
    官方 Sora 2 在镜头运动、物体物理、人物表情等细节上的指令遵循能力领先同档模型。
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="图生视频（input_reference）" icon="image">
    上传一张图片作为视频起始帧，让静态画面"动起来"。详见 [图生视频](/api-capabilities/sora-2/image-to-video)。
  </Card>

  <Card title="异步任务化" icon="list-check">
    提交后返回 `video_id`，轮询状态、独立下载视频，便于批量管理和断点续传。
  </Card>

  <Card title="OpenAI SDK 直连" icon="plug">
    `base_url=https://api.apiyi.com/v1` 即可用 OpenAI 官方 SDK 调用，完全兼容。
  </Card>

  <Card title="失败不计费" icon="circle-check">
    异步模式下，生成失败、内容审核拦截、服务过载等错误均**不计费**。
  </Card>
</CardGroup>

## 模型定价

按 **视频时长（秒）** 计费，与 OpenAI 官方同价。`sora-2-pro` 按分辨率分三档单价。

### `sora-2`（标准版）

| 分辨率                     | 单价       | 4 秒    | 8 秒    | 12 秒   |
| ----------------------- | -------- | ------ | ------ | ------ |
| `720x1280` / `1280x720` | \$0.10/秒 | \$0.40 | \$0.80 | \$1.20 |

### `sora-2-pro`（专业版）

| 分辨率                       | 单价       | 4 秒    | 8 秒    | 12 秒   |
| ------------------------- | -------- | ------ | ------ | ------ |
| `720x1280` / `1280x720`   | \$0.30/秒 | \$1.20 | \$2.40 | \$3.60 |
| `1024x1792` / `1792x1024` | \$0.50/秒 | \$2.00 | \$4.00 | \$6.00 |
| `1080x1920` / `1920x1080` | \$0.70/秒 | \$2.80 | \$5.60 | \$8.40 |

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

  * 按 **实际生成视频秒数** 计费（`seconds` 参数 × 单价），与 prompt 长度、是否传 `input_reference` 无关
  * 异步模式下生成失败 / 内容审核拦截 / 服务过载错误**均不计费**
  * 请求需走 **按量计费** 模式（在 API易 控制台 API Key 设置中切换），按次计费分组无法路由到官转通道
  * 充值加赠政策见 [充值加赠活动](/faq/recharge-promotions)
</Info>

## 分组介绍

Sora 2 官转走专属分组 `Sora2Official`（1x），**令牌必须满足两个条件**才能成功路由：

1. **计费模式**：选「按量优先」（即按量计费）—— 按次计费的令牌无法路由到官转通道
2. **分组**：必须包含 `Sora2Official`

<Frame caption="令牌创建：计费模式选「按量优先」，分组选 Sora2Official 才能调用 sora-2 / sora-2-pro 官转">
  <img src="https://mintcdn.com/apiyillc/bq0-YYlFr270FvfA/images/sora2-token-group-setup-20260501.png?fit=max&auto=format&n=bq0-YYlFr270FvfA&q=85&s=ca71feec9a647195cab7a5bfa41ada2e" alt="令牌创建界面：计费模式选「按量优先」，分组下拉框中勾选 Sora2Official（1x），稳定 OpenAI 官转按秒计费" width="1260" height="970" data-path="images/sora2-token-group-setup-20260501.png" />
</Frame>

两种推荐配置方式，按业务隔离需要选：

| 配置            | 适用场景                                | 配法                                                                                                                |
| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **A. 一把令牌通用** | 同一令牌还要调用其它常规模型（GPT / Claude / 图像 等） | 主分组保留 `Default`（或你常用的分组），**兜底分组**填 `Sora2Official`——非 Sora 请求走主分组，调 `sora-2` / `sora-2-pro` 时自动落到 `Sora2Official` |
| **B. 专用令牌**   | 视频业务独立、需要独立账单与额度管控                  | 新建一把令牌，**只勾选 `Sora2Official` 分组**，专用于 Sora 2 调用                                                                   |

<Tip>
  生产视频业务推荐 **B（专用令牌）**：账单清晰、便于控量与额度告警。A 适合单人开发或低频调用场景。
</Tip>

## 技术规格

| 维度                         | sora-2                                                           | sora-2-pro                                                                      |
| -------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Model ID**               | `sora-2`                                                         | `sora-2-pro`                                                                    |
| **当前 snapshot**            | `sora-2-2025-12-08`                                              | 与别名同步                                                                           |
| **官方 deprecated snapshot** | `sora-2-2025-10-06`                                              | —                                                                               |
| **支持分辨率**                  | `720x1280` / `1280x720`                                          | `720x1280` / `1280x720` / `1024x1792` / `1792x1024` / `1080x1920` / `1920x1080` |
| **支持时长（seconds）**          | `4` / `8` / `12`                                                 | `4` / `8` / `12`                                                                |
| **音轨**                     | ✅ 同步音视频                                                          | ✅ 同步音视频                                                                         |
| **图生视频（input\_reference）** | ✅                                                                | ✅                                                                               |
| **典型生成耗时**                 | 3–5 分钟                                                           | 5–10 分钟                                                                         |
| **视频存储时效**                 | 1 天                                                              | 1 天                                                                             |
| **响应字段**                   | `id` / `status` / `progress` / 视频通过 `/v1/videos/{id}/content` 下载 | 同                                                                               |

## 端点一览

| 端点                              | 方法   | 用途                    | Content-Type                               |
| ------------------------------- | ---- | --------------------- | ------------------------------------------ |
| `/v1/videos`                    | POST | 提交视频生成任务（支持文生视频与图生视频） | `application/json` 或 `multipart/form-data` |
| `/v1/videos/{video_id}`         | GET  | 查询任务状态和进度             | —                                          |
| `/v1/videos/{video_id}/content` | GET  | 下载已生成的视频文件            | —                                          |

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

## 关键参数详解

### `seconds`（视频时长）

仅支持三档枚举值，**字符串类型**（不是数字）：

| 值      | 含义      | 适用场景            |
| ------ | ------- | --------------- |
| `"4"`  | 4 秒（默认） | 短演示、表情包、单镜头     |
| `"8"`  | 8 秒     | 标准短视频，社媒分享、广告片段 |
| `"12"` | 12 秒    | 长镜头、连续动作、剧情片段   |

<Warning>
  `seconds` 必须传**字符串** `"4"` / `"8"` / `"12"`，传数字 `4` 或其它值（如 `"10"` / `"15"`）会返回 400 错误。
</Warning>

### `size`（输出分辨率）

`sora-2` 与 `sora-2-pro` 支持的档位不同：

| 档位      | 像素          | sora-2 | sora-2-pro  |
| ------- | ----------- | ------ | ----------- |
| 720p 竖  | `720x1280`  | ✅      | ✅（\$0.30/秒） |
| 720p 横  | `1280x720`  | ✅      | ✅（\$0.30/秒） |
| 1024p 竖 | `1024x1792` | ❌      | ✅（\$0.50/秒） |
| 1024p 横 | `1792x1024` | ❌      | ✅（\$0.50/秒） |
| 1080p 竖 | `1080x1920` | ❌      | ✅（\$0.70/秒） |
| 1080p 横 | `1920x1080` | ❌      | ✅（\$0.70/秒） |

<Warning>
  * 给 `sora-2` 传 1024p / 1080p 的 size 会返回 400
  * 实际渲染的 sora-2 720p 视频垂直方向像素为 **704**（而非 720），是 OpenAI 官方的实际表现，不影响显示
  * **使用 `input_reference` 图生视频时，参考图片分辨率必须与 `size` 完全一致**，否则报错 `Inpaint image must match the requested width and height`
</Warning>

## 最佳实践

<Steps>
  <Step title="按需选模型">
    * **追求性价比** → `sora-2`（仅 720p，\$0.10/秒，单条 4 秒成本 \$0.40）
    * **要 1080p 全高清 / 强指令遵循** → `sora-2-pro`（最高 \$0.70/秒，支持 1920×1080）
    * **试水 / 内部演示** → `sora-2` 4 秒起步
  </Step>

  <Step title="先调通 4 秒再放大时长">
    每个 prompt 先用 `seconds: "4"` 快速验证镜头方向、风格是否符合预期（耗时 ≈ 3 分钟、单价 \$0.40），定型后再放大到 8 / 12 秒。
  </Step>

  <Step title="先用 byte 计费模式">
    在 API易 控制台 API Key 设置中切换到 **按量计费**，并选择 **Sora2官转** 分组。按次计费分组无法路由到官转通道。
  </Step>

  <Step title="走异步轮询而不是同步等待">
    官转通道**仅支持异步模式**：先 POST 提交拿 `video_id`，再每 10–30 秒轮询 `/v1/videos/{id}` 直到 `status: "completed"`，最后从 `/v1/videos/{id}/content` 下载。
  </Step>

  <Step title="客户端超时 ≥ 30 秒">
    POST 提交本身只是入队，**不会**阻塞到生成完成。但走 multipart 上传 `input_reference` 时，大图上传会拉长建连时间，超时建议 30 秒起步。
  </Step>

  <Step title="生成视频立即下载">
    视频在 OpenAI 上**仅保留 1 天**，过期后 `/content` 端点会 404。生产场景务必拿到 `completed` 后立即落地到自己的 OSS / CDN。
  </Step>

  <Step title="图生视频对齐分辨率">
    上传 `input_reference` 时，提前用本地 ffmpeg/PIL 把图片裁切到目标 `size`（如 `1280x720`），避免 400 报错浪费一次提交。
  </Step>
</Steps>

## 错误码与重试

| 状态码         | 含义                                                           | 处理建议                                |
| ----------- | ------------------------------------------------------------ | ----------------------------------- |
| `400`       | 参数非法（seconds 不在 4/8/12、size 不支持、input\_reference 与 size 不匹配） | 校验参数；图片提前裁切到目标分辨率                   |
| `401`       | 令牌无效                                                         | 检查 Bearer Token 与分组配置（必须 `Sora2官转`） |
| `403`       | 内容审核拦截 / 计费模式错误                                              | 调整 prompt；确认 API Key 走"按量计费"        |
| `429`       | 限流 / 余额不足                                                    | 指数退避重试；充值后立即可用                      |
| `5xx`       | 网关 / 上游错误                                                    | 异步任务重试 1–2 次（不计费）                   |
| 任务 `failed` | 视频生成失败（多为内容审核或上游容量）                                          | 调整 prompt 重试；**该任务不计费**             |

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

  * POST 提交超时 **30 秒**（multipart 上传可能更慢）
  * GET 轮询间隔 **10–30 秒**，最长等待 **15 分钟**（Pro 1080p 12 秒可能 8–10 分钟）
  * 对 5xx 与任务 `failed` 做 **指数退避重试**（建议 2 次）
  * 记录响应头 `x-request-id` 方便排查
</Info>

## 常见问题

<AccordionGroup>
  <Accordion title="官转和官逆有什么区别？现在还能用官逆吗？">
    **官转（本页）**：直接转发到 OpenAI 官方 `/v1/videos`，请求/响应字段与官方一致，按秒计费、稳定性 99.99%、需要按量计费分组。

    **官逆**：通过逆向工程实现的 Sora 2 接口，按次计费、价格更便宜但受 OpenAI 风控影响。**截至 2026 年 1 月 OpenAI 政策调整后，免费账号被关闭，目前 API易 仅保留官转通道。** 如有特殊需求请联系商务。
  </Accordion>

  <Accordion title="为什么必须切换到「按量计费」？">
    官转通道按 **OpenAI 实际秒数** 结算，与"按次"不是同一个计费维度。在 API易 控制台把 API Key 切到 **按量计费** + **Sora2官转 分组** 才能走通这条链路；按次计费分组的请求会直接 403。
  </Accordion>

  <Accordion title="为什么官转只支持异步？没有同步流式？">
    OpenAI 官方 `/v1/videos` 本身就是**异步任务式**端点，没有 SSE 或 WebSocket 流式。生成 4 秒视频通常 3–5 分钟，12 秒可达 8–10 分钟，同步等待会让 HTTP 连接长时间挂起，反而不稳定。建议永远走 POST → 轮询 → 下载 三步。
  </Accordion>

  <Accordion title="seconds 支持哪些值？为什么不能传 10 / 15？">
    OpenAI 官方目前只开放 `"4"` / `"8"` / `"12"` 三个枚举字符串值。10 / 15 是早期官逆通道的非官方时长，**官转通道不支持**。如果你的脚本写的是 `"10"`，改成 `"8"` 或 `"12"` 即可。
  </Accordion>

  <Accordion title="sora-2-pro 1080p 的 \$0.70/秒 是新加的吗？">
    是。OpenAI 官方在最近的更新里把 `sora-2-pro` 的分辨率扩展到 `1080x1920` / `1920x1080` 全高清档位，对应单价 \$0.70/秒。原来的 720p (\$0.30) 和 1024p (\$0.50) 两档单价不变。本页定价表已同步官方最新口径。
  </Accordion>

  <Accordion title="生成视频可以保存多久？">
    视频在 OpenAI 服务器上**只保留 1 天**，过期后 `/v1/videos/{id}/content` 会返回 404 / 410。生产场景务必拿到 `status: "completed"` 后立即下载并落地到自己的 OSS / CDN。
  </Accordion>

  <Accordion title="生成失败会扣费吗？">
    **不会**。异步任务进入 `failed` 状态、内容审核拦截、服务过载、参数错误等情况均不计费。**只有任务真正进入 `completed` 状态、产出视频文件后才按秒计费**。
  </Accordion>

  <Accordion title="可以用 OpenAI 官方 SDK 直连吗？">
    可以。OpenAI Python SDK 1.50+ 已支持 `videos` 命名空间。把 `base_url` 指向 `https://api.apiyi.com/v1` 即可：

    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1")
    video = client.videos.create(
        model="sora-2",
        prompt="A golden retriever running on the beach at sunset",
        seconds="8",
        size="1280x720"
    )
    print(video.id, video.status)
    ```
  </Accordion>

  <Accordion title="input_reference 接受 base64 吗？">
    不接受。`input_reference` 是 **multipart/form-data 文件上传字段**（接受 `image/jpeg` / `image/png` / `image/webp`），需要走 multipart 请求。如果图片在 base64，先 decode 写到临时文件再上传。详见 [图生视频](/api-capabilities/sora-2/image-to-video)。
  </Accordion>

  <Accordion title="音轨可以关闭吗？">
    **目前不支持**。Sora 2 / Pro 默认输出带同步音轨的视频（环境音、对话、配乐），官方未开放禁用音轨的参数。如需纯视频，下载后用 ffmpeg `-an` 剥离即可。
  </Accordion>

  <Accordion title="可以主动取消正在生成的任务吗？">
    **不支持**。OpenAI 官方 `/v1/videos` 没有提供 cancel 端点，任务一旦提交会跑完。建议先用 `seconds: "4"` 试水 prompt，确认风格再放大时长，避免长任务跑废。
  </Accordion>

  <Accordion title="速率限制是多少？">
    遵循 OpenAI 官方账号 Tier 限制，但通过 API易 网关聚合后默认无明显瓶颈。**企业批量需求**（>10 并发、单日 >100 条）请联系商务申请独立资源池。
  </Accordion>

  <Accordion title="可以同时跑多个任务吗？">
    可以。每次 POST `/v1/videos` 返回独立的 `video_id`，多任务并发提交、独立轮询。建议客户端用任务队列管理 video\_id 列表，避免轮询风暴。
  </Accordion>
</AccordionGroup>

## 相关文档

* [文生视频 Playground](/api-capabilities/sora-2/text-to-video) - `POST /v1/videos`（JSON）在线调试，5 段语言代码示例
* [图生视频 Playground](/api-capabilities/sora-2/image-to-video) - `POST /v1/videos`（multipart）+ `input_reference` 用法详解
* [充值加赠活动](/faq/recharge-promotions) - 加赠最高档位与适用渠道
* [API 使用手册](/api-manual) - 通用调用规范、超时与重试建议
* OpenAI 官方模型页：`platform.openai.com/docs/models/sora-2`
* OpenAI 官方接口文档：`platform.openai.com/docs/api-reference/videos/create`

<Info>
  Sora 2 系列是 API易 通过官方授权 Plus 级账号池实现的稳定官转服务。响应字段、错误码、计费维度与 OpenAI 官方完全一致，便于无缝对接已有代码。如有问题或建议，欢迎在控制台工单中反馈。
</Info>