Skip to main content
本文將介紹 Sora Videos Generation API 的對接說明，通過該 API 可以輸入自定義參數來生成 Sora 官方的視頻。本 API 支持兩種版本模式：
  • Version 1（經典模式）：支持 duration（10/15/25 秒）、orientation（橫屏/豎屏）、size（small/large 清晰度）、參考圖 image_urls、角色視頻 character_url 等參數。
  • Version 2（合作商模式）：支持 seconds（4/8/12 秒）、像素級分辨率 size（如 1280x720）、參考圖 input_reference 等參數。

​
申請流程

要使用 Sora Videos Generation API，首先到 Ace Data Cloud 控制台 獲取您的 API Token，留作備用。 如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在 控制台 充值通用餘額。
📘 完整文檔：Sora Videos Generation API →

​
基本使用（Version 1）

首先先了解 Version 1 的基本使用方式，就是輸入提示詞 prompt、參考圖片鏈接數組 image_urls 以及模型 model，便可獲得處理後的結果，具體的內容如下：

可以看到這裡我們設置了 Request Headers，包括：
  • accept：想要接收怎樣格式的響應結果，這裡填寫為 application/json，即 JSON 格式。
  • authorization：調用 API 的密鑰，申請之後可以直接下拉選擇。
另外設置了 Request Body，包括：
  • model：生成視頻的模型，支持 sora-2（標準模式）和 sora-2-pro（高清模式）。其中 sora-2-pro 可以支持 duration 為 25 秒的視頻，而 sora-2 只支持 10、15 秒。
  • size：視頻清晰度，small 為標準清晰度、large 為 HD 清晰度（僅 Version 1）。
  • duration：視頻時長，支持 10、15、25 秒，其中 25 秒僅 sora-2-pro 支持（僅 Version 1）。
  • orientation：畫幅方向，支持 landscape（橫屏）、portrait（豎屏）（僅 Version 1）。
  • image_urls：參考圖片鏈接數組，用於圖生視頻（僅 Version 1）。
  • character_url：角色視頻鏈接，視頻中不能出現真人（僅 Version 1）。
  • character_start/character_end：角色出現的起止秒數，範圍差值為 1-3 秒（僅 Version 1）。
  • prompt：提示詞（必填）。
  • callback_url：異步回調結果的 URL。
  • async：可選，設為 true 時接口立即返回 task_id，無需提供 callback_url，隨後通過對應的任務查詢接口輪詢獲取結果。
  • version：API 版本，"1.0"（默認）或 "2.0"。
選擇之後，可以發現右側也生成了對應代碼，如圖所示：

點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果：
返回結果一共有多個字段，介紹如下：
  • success，此時視頻生成任務的狀態情況。
  • task_id，此時視頻生成任務ID。
  • trace_id，此時視頻生成跟蹤ID。
  • data，此時視頻生成任務的結果列表。
    • id，此時視頻生成任務的視頻ID。
    • video_url，此時視頻生成任務的視頻鏈接。
    • state，此時視頻生成任務的狀態。
可以看到我們得到了滿意的視頻信息，我們只需要根據結果中 data 的視頻鏈接地址獲取生成的Sora視頻即可。 另外如果想生成對應的對接代碼，可以直接複製生成，例如 CURL 的代碼如下：

​
圖生視頻任務（Version 1）

如果想進行圖生視頻任務，首先參數 image_urls 必須傳入參考圖片鏈接，就可以指定如下內容：
  • image_urls：該圖生視頻任務采用的參考圖鏈接數組。注意不可傳遞真實的帶有頭像的人物圖像，否則可能導致任務失敗。
填寫樣例如下：

填寫完畢之後自動生成了代碼如下：

對應的代碼：
點擊運行，可以發現會立即得到一個結果，如下：
可以看到，生成的效果是圖生建視頻的，結果與上文類似。

​
角色生成視頻任務（Version 1）

如果想進行角色生成視頻任務，首先參數 character_url 必須傳入創建角色需要的視頻鏈接，注意視頻中一定不能出現真人，否則會失敗，就可以指定如下內容：
  • character_url：創建角色需要的視頻鏈接，注意視頻中一定不能出現真人，否則會失敗。
填寫樣例如下：

填寫完畢之後自動生成了代碼如下：

對應的代碼：
點擊運行，可以發現會立即得到一個結果，如下：
可以看到，生成的效果是角色生成視頻，結果與上文類似。

​
Version 2.0 模式

除了上述 Version 1.0 模式之外，本 API 還支持 Version 2.0 模式，通過設置 version 參數為 "2.0" 即可啟用。Version 2.0 模式支持更短的視頻時長和像素級的分辨率控制。

​
Version 2.0 參數說明

​
基本示例

對應的 Python 代碼：
對應的 JavaScript 代碼：
返回結果格式與 Version 1 相同：

​
使用參考圖片（Version 2.0）

在 Version 2.0 模式下，可以通過 image_urls 參數傳入參考圖片來引導視頻生成（僅使用第一張圖片）：
注意：參考圖片的尺寸應與 size 參數保持一致，例如 size 為 1280x720 時，參考圖片尺寸應為 1280×720。

​
Version 1.0 與 Version 2.0 參數對比

​
非同步回調

由於 Sora Videos Generation API生成的時間相對較長，大約需要 1-2 分鐘，如果 API 長時間無響應，HTTP 請求會一直保持連接，導致額外的系統資源消耗，所以本 API 也提供了非同步回調的支持。 整體流程是：客戶端發起請求的時候，額外指定一個 callback_url 字段，客戶端發起 API 請求之後，API 會立馬返回一個結果，包含一個 task_id 的字段信息，代表當前的任務 ID。當任務完成之後，生成視頻的結果會通過 POST JSON 的形式發送到客戶端指定的 callback_url，其中也包括了 task_id 字段，這樣任務結果就可以通過 ID 關聯起來了。 下面我們通過示例來了解下具體怎樣操作。 首先，Webhook 回調是一個可以接收 HTTP 請求的服務，開發者應該替換為自己搭建的 HTTP 伺服器的 URL。此處為了方便演示，使用一個公開的 Webhook 樣例網站 https://webhook.site/，打開該網站即可得到一個 Webhook URL，如圖所示： 將此 URL 複製下來，就可以作為 Webhook 來使用，此處的樣例為 https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa。 接下來，我們可以設置字段 callback_url 為上述 Webhook URL，同時填入相應的參數，具體的內容如圖所示：

點擊運行，可以發現會立即得到一個結果，如下：
稍等片刻，我們可以在 https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa 上觀察到生成視頻的結果，如圖所示： 內容如下：
可以看到結果中有一個 task_id 字段，其他的字段都和上文類似，通過該字段即可實現任務的關聯。

​
錯誤處理

在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如：
  • 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token：Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests：Too many requests, you have exceeded the rate limit.
  • 500 api_error：Internal server error, something went wrong on the server.

​
錯誤響應示例

​
結論

通过本文档，您已经了解了如何使用 Sora Videos Generation API 可通过输入提示词以及参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。