跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

本文將介紹 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 等參數。

​
申請流程

要使用 API，需要先到 Sora Videos Generation API 對應頁面申請對應的服務，進入頁面之後，點擊「Acquire」按鈕，如圖所示： 如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。 在首次申請時會有免費額度贈送，可以免費使用該 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。
  • version：API 版本，"1.0"（預設）或 "2.0"。
選擇之後，可以發現右側也生成了對應程式碼，如圖所示：

點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果： 
{
  "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://filesystem.site/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 的程式碼如下： 
curl -X POST 'https://api.xhuoapi.ai/v1/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：該圖生影片任務採用的參考圖連結陣列。注意不可傳遞真實的帶有頭像的人物圖像，否則可能導致任務失敗。
填寫範例如下：

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

對應的程式碼： 
import requests

url = "https://api.xhuoapi.ai/v1/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "size": "large",
    "duration": 15,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "image_urls": ["https://cdn.xhuoapi.ai/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://filesystem.site/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：建立角色需要的影片連結，注意影片中一定不能出現真人，否則會失敗。
填寫範例如下：

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

對應的程式碼： 
import requests

url = "https://api.xhuoapi.ai/v1/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "size": "small",
    "duration": 10,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "character_url": "https://cdn.xhuoapi.ai/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://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}
可以看到，生成的效果是角色生成影片，結果與上文類似。

​
Version 2.0 模式

除了上述 Version 1.0 模式之外，本 API 還支援 Version 2.0 模式，透過設定 version 參數為 "2.0" 即可啟用。Version 2.0 模式支援更短的影片時長和像素級的解析度控制。

​
Version 2.0 參數說明

參數類型是否必填說明
versionstring是設定為 "2.0"
promptstring是生成影片的提示詞
modelstring否sora-2（預設）或 sora-2-pro
durationinteger否影片時長：4（預設）、8、12 秒
sizestring否解析度：720x1280（預設）、1280x720、1024x1792、1792x1024
image_urlsarray否參考圖片 URL 陣列，僅使用第一張圖片，圖片尺寸需要與 size 參數一致
callback_urlstring否非同步回調 URL

​
基本範例

curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "version": "2.0",
  "prompt": "cat running on the river",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'
對應的 Python 程式碼： 
import requests

url = "https://api.xhuoapi.ai/v1/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "version": "2.0",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
對應的 JavaScript 程式碼： 
const response = await fetch('https://api.xhuoapi.ai/v1/sora/videos', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'authorization': 'Bearer {token}',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    version: '2.0',
    prompt: 'cat running on the river',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);
返回結果格式與 Version 1 相同： 
{
  "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.xhuoapi.ai/sora/xxxxx.mp4",
      "state": "succeeded"
    }
  ]
}

​
使用參考圖片（Version 2.0）

在 Version 2.0 模式下，可以透過 image_urls 參數傳入參考圖片來引導影片生成（僅使用第一張圖片）： 
import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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.0Version 2.0
version1.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/，打開該網站即可得到一個 Webhook URL，如圖所示： 將此 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 上觀察到生成影片的結果，如圖所示： 內容如下： 
{
    "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://filesystem.site/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，可能因為缺少或無效參數。
  • 400 api_not_implemented：Bad request，可能因為缺少或無效參數。
  • 401 invalid_token：Unauthorized，無效或缺少授權令牌。
  • 429 too_many_requests：請求過多，您已超過速率限制。
  • 500 api_error：內部伺服器錯誤，伺服器發生異常。

​
錯誤響應範例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
結論

透過本文檔，您已經了解了如何使用 Sora Videos Generation API 可透過輸入提示詞以及參考圖片來生成影片。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支援團隊。