> ## 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="/zh-Hant/api-capabilities/sora-2/text-to-video">
    `POST /v1/videos`，純文本提示詞生成影片，JSON 請求體，最簡單的入口。
  </Card>

  <Card title="圖生影片 API" icon="image" href="/zh-Hant/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 官方一致，疊加 [充值加贈活動](/zh-Hant/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">
    上傳一張圖片作為影片起始幀，讓靜態畫面"動起來"。詳見 [圖生影片](/zh-Hant/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 設定中切換），按次計費分組無法路由到官轉通道
  * 充值加贈政策見 [充值加贈活動](/zh-Hant/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 寫到臨時檔案再上傳。詳見 [圖生影片](/zh-Hant/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](/zh-Hant/api-capabilities/sora-2/text-to-video) - `POST /v1/videos`（JSON）線上除錯，5 段語言程式碼示例
* [圖生影片 Playground](/zh-Hant/api-capabilities/sora-2/image-to-video) - `POST /v1/videos`（multipart）+ `input_reference` 用法詳解
* [充值加贈活動](/zh-Hant/faq/recharge-promotions) - 加贈最高檔位與適用渠道
* [API 使用手冊](/zh-Hant/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>