> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Sora Videos Generation API 對接說明 > Sora Video Generation 整合指南 - Ace Data Cloud 本文將介紹 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 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。 ![](https://cdn.acedata.cloud/5hmkdg.jpg) 如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 **一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。 > 📘 完整文檔：[Sora Videos Generation API →](https://platform.acedata.cloud/documents/sora-videos) ## 基本使用（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」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果： ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh", "video_url": "https://platform.cdn.acedata.cloud/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` 返回結果一共有多個字段，介紹如下： * `success`，此時視頻生成任務的狀態情況。 * `task_id`，此時視頻生成任務ID。 * `trace_id`，此時視頻生成跟蹤ID。 * `data`，此時視頻生成任務的結果列表。 * `id`，此時視頻生成任務的視頻ID。 * `video_url`，此時視頻生成任務的視頻鏈接。 * `state`，此時視頻生成任務的狀態。 可以看到我們得到了滿意的視頻信息，我們只需要根據結果中 `data` 的視頻鏈接地址獲取生成的Sora視頻即可。 另外如果想生成對應的對接代碼，可以直接複製生成，例如 CURL 的代碼如下： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2" }' ``` ## 圖生視頻任務（Version 1） 如果想進行圖生視頻任務，首先參數 `image_urls` 必須傳入參考圖片鏈接，就可以指定如下內容： * `image_urls`：該圖生視頻任務采用的參考圖鏈接數組。注意不可傳遞真實的帶有頭像的人物圖像，否則可能導致任務失敗。 填寫樣例如下：

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

對應的代碼： ```python theme={null} import requests url = "https://api.acedata.cloud/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "large", "duration": 15, "orientation": "landscape", "prompt": "貓在河上奔跑", "model": "sora-2", "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 點擊運行，可以發現會立即得到一個結果，如下： ``` { "success": true, "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a", "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172", "data": [ { "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws", "video_url": "https://platform.cdn.acedata.cloud/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` 可以看到，生成的效果是圖生建視頻的，結果與上文類似。 ## 角色生成視頻任務（Version 1） 如果想進行角色生成視頻任務，首先參數 `character_url` 必須傳入創建角色需要的視頻鏈接，注意視頻中一定不能出現真人，否則會失敗，就可以指定如下內容： * character\_url：創建角色需要的視頻鏈接，注意視頻中一定不能出現真人，否則會失敗。 填寫樣例如下：

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

對應的代碼： ```python theme={null} import requests url = "https://api.acedata.cloud/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "small", "duration": 10, "orientation": "landscape", "prompt": "貓在河上奔跑", "character_url": "https://cdn.acedata.cloud/pdidf5.mp4", "model": "sora-2", "character_end": 3, "character_start": 1 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 點擊運行，可以發現會立即得到一個結果，如下： ``` { "success": true, "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259", "trace_id": "b7992643-9207-40d6-956b-7577728acc67", "data": [ { "id": "sora-2:task_01k8ykrztefavaypw6xanw305b", "video_url": "https://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4", "state": "succeeded" } ] } ``` 可以看到，生成的效果是角色生成視頻，結果與上文類似。 ## Version 2.0 模式 除了上述 Version 1.0 模式之外，本 API 還支持 Version 2.0 模式，通過設置 `version` 參數為 `"2.0"` 即可啟用。Version 2.0 模式支持更短的視頻時長和像素級的分辨率控制。 ### Version 2.0 參數說明 | 參數 | 類型 | 是否必填 | 說明 | | -------------- | ------- | ---- | ----------------------------------------------------- | | `version` | string | 是 | 設置為 `"2.0"` | | `prompt` | string | 是 | 生成視頻的提示詞 | | `model` | string | 否 | `sora-2`（默認）或 `sora-2-pro` | | `duration` | integer | 否 | 視頻時長：`4`（默認）、`8`、`12` 秒 | | `size` | string | 否 | 分辨率：`720x1280`（默認）、`1280x720`、`1024x1792`、`1792x1024` | | `image_urls` | array | 否 | 參考圖片 URL 陣列，僅使用第一張圖片，圖片尺寸需要與 `size` 參數一致 | | `callback_url` | string | 否 | 異步回調 URL | ### 基本示例 ```shell theme={null} curl -X POST 'https://api.acedata.cloud/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "version": "2.0", "prompt": "貓在河上奔跑", "model": "sora-2", "duration": 8, "size": "1280x720" }' ``` 對應的 Python 代碼： ```python theme={null} import requests url = "https://api.acedata.cloud/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "貓在河上奔跑", "model": "sora-2", "seconds": 8, "size": "1280x720" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 對應的 JavaScript 代碼： ```javascript theme={null} const response = await fetch('https://api.acedata.cloud/sora/videos', { method: 'POST', headers: { 'accept': 'application/json', 'authorization': 'Bearer {token}', 'content-type': 'application/json' }, body: JSON.stringify({ version: '2.0', prompt: '貓在河上奔跑', model: 'sora-2', seconds: 8, size: '1280x720' }) }); const data = await response.json(); console.log(data); ``` 返回結果格式與 Version 1 相同： ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "c0cc8dad-0954-421f-be8d-02eb063b3263", "video_url": "https://platform.cdn.acedata.cloud/sora/xxxxx.mp4", "state": "succeeded" } ] } ``` ### 使用參考圖片（Version 2.0） 在 Version 2.0 模式下，可以通過 `image_urls` 參數傳入參考圖片來引導視頻生成（僅使用第一張圖片）： ```python theme={null} import requests url = "https://api.acedata.cloud/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "a person walking through a beautiful garden", "model": "sora-2", "duration": 4, "size": "1280x720", "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` > **注意**：參考圖片的尺寸應與 `size` 參數保持一致，例如 `size` 為 `1280x720` 時，參考圖片尺寸應為 1280×720。 ### Version 1.0 與 Version 2.0 參數對比 | 參數 | Version 1.0 | Version 2.0 | | --------------- | --------------------- | --------------------------------------- | | `version` | 1.0（默認） | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 秒 | ✅ 4/8/12 秒 | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ 多張參考圖 | ✅ 僅使用第一張 | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## 非同步回調 由於 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/，打開該網站即可得到一個](https://webhook.site/，打開該網站即可得到一個) Webhook URL，如圖所示： ![](https://cdn.acedata.cloud/cjjfly.png) 將此 URL 複製下來，就可以作為 Webhook 來使用，此處的樣例為 `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`。 接下來，我們可以設置字段 `callback_url` 為上述 Webhook URL，同時填入相應的參數，具體的內容如圖所示：

點擊運行，可以發現會立即得到一個結果，如下： ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` 稍等片刻，我們可以在 `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa` 上觀察到生成視頻的結果，如圖所示： ![](https://cdn.acedata.cloud/0j7nra.png) 內容如下： ```json theme={null} { "success": true, "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2", "data": [ { "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5", "video_url": "https://platform.cdn.acedata.cloud/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` 可以看到結果中有一個 `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. ### 錯誤響應示例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 結論 通过本文档，您已经了解了如何使用 Sora Videos Generation API 可通过输入提示词以及参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。