For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

使用 Sora 生成影片

使用 Videos API 建立、反覆調整及管理影片。

The Sora 2 video generation models and Videos API are deprecated and will shut down on September 24, 2026. This affects Videos API, sora-2, sora-2-pro, sora-2-2025-10-06, sora-2-2025-12-08, and sora-2-pro-2025-10-06. See the deprecations page for details.

概覽

Sora 是 OpenAI 在生成式媒體領域的最新前沿成果。這款先進的影片模型能根據自然語言或圖像,創作出細節豐富、動態生動且附有音訊的短片。Sora 以多年的多模態擴散研究為基礎,並使用多樣化的視覺資料進行訓練,將對 3D 空間、動作及場景連貫性的深入理解運用於文字轉影片生成。

Videos API 首次向開發人員開放這些能力,讓開發人員能以程式建立、延長、編輯及管理影片。

你可以使用它來:

  • 根據提示詞建立新影片。
  • 使用參考圖像引導生成。
  • 在多次生成中重複使用角色素材,提高視覺一致性。
  • 使用影片延長功能接續已完成的短片。
  • 針對現有影片進行特定修改。
  • 下載已完成的影片及輔助素材。
  • 透過 Batch API 提交大量離線算繪佇列。

模型

第二代 Sora 模型提供兩種版本,各自針對不同的使用案例設計。

Sora 2

sora-2 著重於 速度與彈性。在探索階段,如果你正在嘗試不同的調性、結構或視覺風格,需要快速回饋而非完美的擬真度,它會是理想的選擇。

它能快速生成品質良好的成果,非常適合快速反覆調整、構思概念及製作粗剪。對於社群媒體內容、原型,以及比起極高擬真度更重視交付速度的情境,sora-2 通常已綽綽有餘。

Sora 2 Pro

sora-2-pro 能產生更高品質的成果。當你需要 達到正式製作品質的輸出時,它會是更好的選擇。

sora-2-pro 的算繪時間較長,使用成本也較高,但能產生更精緻、穩定的成果。它最適合高解析度的電影感影像、行銷素材,以及任何對視覺精準度要求嚴格的情境。

如果需要以 1920x10801080x1920 匯出 1080p 影片,請使用 sora-2-pro

sora-2sora-2-pro 都支援生成 16 秒及 20 秒的影片。

生成影片

影片生成是 非同步 流程:

  1. 呼叫 POST /videos 端點時,API 會傳回作業物件,其中包含作業的 id 和初始 status

  2. 你可以輪詢 GET /videos/{video_id} 端點,直到狀態變為已完成;也可以採用更有效率的方式,使用 webhooks(請參閱下方的 webhooks 章節),在作業完成時自動接收通知。

  3. 作業達到 completed 狀態後,你就能使用 GET /videos/{video_id}/content 取得最終的 MP4 檔案。

啟動算繪作業

首先,呼叫 POST /videos 並提供文字提示詞和必要參數。提示詞用來定義創作的視覺風格與氛圍,包括主體、鏡頭、光線及動作;sizeseconds 等參數則用來控制影片的解析度與長度。

建立影片
import OpenAI from "openai";

const openai = new OpenAI();

let video = await openai.videos.create({
  model: "sora-2",
  prompt: "A video of the words 'Thank you' in sparkling letters",
});

console.log("Video generation started: ", video);

回應是 JSON 物件,包含唯一的 id 和初始狀態,例如 queuedin_progress。這表示算繪作業已啟動。

{
  "id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5",
  "object": "video",
  "created_at": 1758941485,
  "status": "queued",
  "model": "sora-2-pro",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720"
}

選擇尺寸和長度

選擇能滿足製作需求的最小規格:

  • 反覆調整提示詞、動作或構圖時,請使用較短的片段。
  • 如果需要更長的情節段落、更完整的場景或廣告短片,可以生成最長 20 秒的影片。
  • 使用 sora-2-pro,以 1920x10801080x1920 匯出更高解析度的影片。

較長的影片和 1080p 作業,所需的完成時間可能明顯超過簡短的 720p 或 480p 算繪作業,因此設計使用者操作流程時,請將較長的延遲納入考量。

防護機制與限制

API 會強制執行以下內容限制:

  • 僅允許適合未滿 18 歲觀眾的內容(未來將提供可略過此限制的設定)。
  • 受著作權保護的角色和音樂將遭拒絕。
  • 無法生成真實人物,包括公眾人物。
  • 預設會封鎖呈現人類樣貌的角色上傳內容。
  • 目前會拒絕包含人臉的輸入圖像。

請確保提示詞、參考圖像和逐字稿符合這些規則,以免生成失敗。

撰寫有效的提示詞

為獲得最佳結果,請描述 鏡頭類型、主體、動作、場景和光線。例如:

  • 「遠景鏡頭:一個孩子在綠草如茵的公園裡放紅色風箏,沐浴在黃金時刻的陽光下,鏡頭緩緩向上移動。」
  • 「特寫鏡頭:木桌上的咖啡杯冒著熱氣,晨光透過百葉窗灑入,景深效果柔和。」

這樣具體的描述有助於模型產生一致的結果,避免自行添加不必要的細節。如需更進階的提示詞技巧,請參閱我們專為 Sora 2 撰寫的提示詞指南

監控進度

影片生成需要時間。視模型、API 負載和解析度而定, 單次算繪可能需要數分鐘

為了有效掌握進度,你可以輪詢 API 以取得最新狀態,或透過 webhook 接收通知。

輪詢狀態端點

使用建立作業時傳回的 ID 呼叫 GET /videos/{video_id}。回應會顯示作業的目前狀態、進度百分比(若有提供),以及任何錯誤。

常見狀態包括 queuedin_progresscompletedfailed。請以合理的間隔輪詢(例如每 10–20 秒一次),必要時採用指數退避,並向使用者顯示作業仍在進行中的訊息。

輪詢狀態端點
import OpenAI from "openai";
import { setTimeout as sleep } from "node:timers/promises";

const openai = new OpenAI();

async function main() {
  let video = await openai.videos.create({
    model: "sora-2",
    prompt: "A video of the words 'Thank you' in sparkling letters",
  });

  while (video.status === "queued" || video.status === "in_progress") {
    await sleep(2000);
    video = await openai.videos.retrieve(video.id);
  }

  if (video.status === "completed") {
    console.log("Video successfully completed: ", video);
  } else {
    console.log("Video creation failed. Status: ", video.status);
  }
}

main();

回應範例:

{
  "id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5",
  "object": "video",
  "created_at": 1758941485,
  "status": "in_progress",
  "model": "sora-2-pro",
  "progress": 33,
  "seconds": "8",
  "size": "1280x720"
}

使用 Webhooks 接收通知

你可以註冊 webhook,在影片生成完成或失敗時自動接收通知,無須使用 GET 反覆輪詢作業狀態。

你可以在 webhook 設定頁面設定 Webhooks。作業結束時,API 會發出兩種事件類型之一:video.completedvideo.failed。每個事件都包含觸發該事件的作業 ID。

webhook 酬載範例:

{
  "id": "evt_abc123",
  "object": "event",
  "created_at": 1758941485,
  "type": "video.completed", // or "video.failed"
  "data": {
    "id": "video_abc123"
  }
}

擷取結果

下載 MP4

作業狀態變為 completed 後,即可使用 GET /videos/{video_id}/content 擷取 MP4。此端點會以串流方式傳輸二進位影片資料,並傳回標準內容標頭,因此你可以將檔案直接儲存至磁碟,或透過管線傳送至雲端儲存空間。

下載 MP4
import { writeFileSync } from "node:fs";

import OpenAI from "openai";

const openai = new OpenAI();

let video = await openai.videos.create({
  model: "sora-2",
  prompt: "A video of the words 'Thank you' in sparkling letters",
});

console.log("Video generation started: ", video);
let progress = video.progress ?? 0;

while (video.status === "in_progress" || video.status === "queued") {
  video = await openai.videos.retrieve(video.id);
  progress = video.progress ?? 0;

  // Display progress bar
  const barLength = 30;
  const filledLength = Math.floor((progress / 100) * barLength);
  // Simple ASCII progress visualization for terminal output
  const bar = "=".repeat(filledLength) + "-".repeat(barLength - filledLength);
  const statusText = video.status === "queued" ? "Queued" : "Processing";

  process.stdout.write(`${statusText}: [${bar}] ${progress.toFixed(1)}%`);

  await new Promise((resolve) => setTimeout(resolve, 2000));
}

// Clear the progress line and show completion
process.stdout.write("\n");

if (video.status === "failed") {
  throw new Error("Video generation failed");
}

console.log("Video generation completed: ", video);

console.log("Downloading video content...");

const content = await openai.videos.downloadContent(video.id);

const body = content.arrayBuffer();
const buffer = Buffer.from(await body);

writeFileSync("video.mp4", buffer);

console.log("Wrote video.mp4");

現在你已取得最終影片檔案,可供播放、編輯或散布。下載 URL 在生成後最多 1 小時內有效。如果需要長期儲存,請盡快將檔案複製到自己的儲存系統。

下載輔助素材

每部完成的影片都提供 縮圖精靈圖集供你下載。這些素材檔案小,適合用於預覽、拖曳進度列預覽或目錄展示。使用 variant 查詢參數指定要下載的內容。預設值為 variant=video,用於下載 MP4。

# Download a thumbnail
curl -L "https://api.openai.com/v1/videos/video_abc123/content?variant=thumbnail" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  --output thumbnail.webp

# Download a spritesheet
curl -L "https://api.openai.com/v1/videos/video_abc123/content?variant=spritesheet" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  --output spritesheet.jpg

使用參考圖像

你可以使用輸入圖像引導生成,該圖像會作為 影片的第一個影格。如果你需要輸出影片保留品牌素材、角色或特定環境的外觀,這個方法會很實用。

請根據請求類型選擇 input_reference 的格式:

  • multipart/form-data 請求中,使用 input_reference 傳入上傳的圖像。
  • application/json 請求(包括批次處理)中,使用 input_reference 傳入 JSON 物件。JSON 格式接受 file_idimage_url

圖像的解析度必須與目標影片的解析度(size)相符。

支援的檔案格式為 image/jpegimage/pngimage/webp

curl -X POST "https://api.openai.com/v1/videos" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F prompt="She turns around and smiles, then slowly walks out of the frame." \
  -F model="sora-2-pro" \
  -F size="1280x720" \
  -F seconds="8" \
  -F input_reference="@sample_720p.jpeg;type=image/jpeg"
使用 OpenAI GPT Image 生成的輸入圖像使用 Sora 2 生成的影片(已轉換為 GIF)
下載此圖像 提示詞: 「她轉過身微笑,接著緩緩走出畫面。」
下載此圖像 提示詞: 「冰箱門打開了。一隻可愛、胖嘟嘟的紫色怪獸從裡面走出來。」

使用角色維持一致性

角色功能讓你上傳可重複使用的非人類主體,並在多次生成時引用。如果你希望動物、吉祥物或物件在多個鏡頭中保持相同的主要外觀、造型和畫面表現,這個功能會很實用。

目前上傳角色時,以長度 24 秒、長寬比為 16:99:16、解析度為 720p1080p 的短片效果最佳。角色來源影片的長寬比 與請求輸出的長寬比相符時,效果最佳。如果長寬比 不同,角色可能會被拉伸或變形。單部影片最多可 包含兩個角色。

角色與 input_reference 不同。參考圖像用於引導 單次生成的起始影格,而角色素材則可在 後續影片請求中重複使用。

將一段 MP4 短片上傳至 POST /v1/videos/characters 以建立角色,接著在建立影片時,將傳回的角色 ID 加入 characters 陣列。

預設會封鎖描繪人類樣貌的角色上傳。如要進一步了解 使用人類樣貌功能的資格,請聯絡你的客戶經理,或聯絡我們的 業務團隊 洽詢。

curl -X POST "https://api.openai.com/v1/videos/characters" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@character.mp4;type=video/mp4" \
  -F "name=Mossy"

請在提示詞中完整寫出角色名稱,不要更動任何字元。僅傳入角色 ID 不足以確保鏡頭中的角色維持一致。

角色可搭配 input_reference 使用。影片延長功能不支援 角色。

curl -X POST "https://api.openai.com/v1/videos" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cinematic tracking shot of Mossy, a moss-covered teapot mascot, weaving through a lantern-lit market at dusk.",
    "size": "1280x720",
    "seconds": "8",
    "characters": [
      { "id": "char_123" }
    ]
  }'

延長已完成的影片

影片延長功能可接續已完成的現有影片,並產生拼接後的新影片。向 POST /v1/videos/extensions 發送請求時,在 video 欄位提供來源影片,並加入描述場景應如何延續的提示詞,API 就會以完整的來源片段作為上下文,生成下一段影片。

如要保持動作、鏡頭方向及場景的連貫性,請使用影片延長功能。如果只需要控制新生成影片的起始畫格,請改用 input_reference

每次延長最多可增加 20 秒。單支影片最多可延長 六次,總長度上限為 120 秒。影片延長功能 目前只接受來源影片和提示詞,不支援角色 或參考圖像。

curl -X POST "https://api.openai.com/v1/videos/extensions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": {
      "id": "video_abc123"
    },
    "prompt": "Continue the scene as the camera rises over the rooftops and reveals the sunrise.",
    "seconds": "8"
  }'

編輯現有影片

編輯功能可讓你針對現有影片進行特定調整,無須從頭重新生成所有內容。發送 POST /v1/videos/edits 請求並附上提示詞和 video 參考,系統就會在套用修改時保留原有的結構、連貫性及構圖。每次只做一項明確的修改效果最好,因為小幅且集中的編輯能保留更多原始細節與品質,也能降低產生畫面瑕疵的風險。

先前可使用 remix 端點編輯生成的影片,但該端點已棄用。 新的整合請使用 edits 端點。

video 欄位接受影片 ID 或上傳的影片。如果傳入 影片 ID,API 會根據來源影片判定所用的模型。

只有符合資格的客戶才能編輯上傳的影片。如果你需要這項工作流程,請聯絡 你的客戶經理,或聯絡我們的 業務團隊

curl -X POST "https://api.openai.com/v1/videos/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": {
      "id": "video_abc123"
    },
    "prompt": "Shift the color palette to teal, sand, and rust, with a warm backlight."
  }'

如果你上傳新影片,而非編輯先前生成的影片,請在請求中明確設定 model

curl -X POST "https://api.openai.com/v1/videos/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@source.mp4;type=video/mp4" \
  -F "model=sora-2-pro" \
  -F "prompt=Shift the color palette to teal, sand, and rust, with a warm backlight."

編輯功能特別適合反覆調整,因為它能讓你在保留滿意成果的同時進一步完善影片。每次編輯只做一項明確的調整,就能維持視覺風格、主體一致性及鏡頭構圖,同時嘗試不同的氛圍、配色或場面安排。這樣便能透過小幅、可靠的調整,更輕鬆地逐步製作出精緻的連續片段。

原始影片編輯後的生成影片
提示詞: 「將怪物的顏色改成橘色。」
提示詞: 「第二隻怪物緊接著走出來。」

透過批次處理 API 執行影片作業

當你需要將大量影片算圖作業排入佇列,以便進行離線處理、審查流程或工作室的工作流程時,可以使用批次處理 API。批次輸入檔案的每一行,都使用與發送至 POST /v1/videos 時相同的 JSON 請求主體,因此很適合用來處理鏡頭清單及排程算圖佇列。

使用批次處理生成影片時:

  • 批次處理目前僅支援 POST /v1/videos
  • 批次處理請求必須使用 JSON,不能使用 multipart。
  • 請事先上傳素材,再從 JSON 請求主體中參照這些素材。
  • 在批次處理中,請使用 input_reference 以圖像引導生成。在 JSON 請求中,請將 input_reference 以包含 file_idimage_url 的物件形式傳入。
  • 批次處理不支援以 multipart 格式上傳 input_reference,其中也包括參考影片輸入。
  • 透過批次處理生成的影片,在批次完成後最多可供下載 24 小時。
{"custom_id":"shot-001","method":"POST","url":"/v1/videos","body":{"model":"sora-2-pro","prompt":"Slow dolly shot through a miniature paper city at blue hour, soft fog, practical window lights flickering on.","size":"1920x1080","seconds":"20"}}
{"custom_id":"shot-002","method":"POST","url":"/v1/videos","body":{"model":"sora-2-pro","prompt":"Portrait close-up of a red panda chef plating noodles in a stainless-steel kitchen, shallow depth of field.","size":"1080x1920","seconds":"16"}}

當批次達到 completed 狀態時,其輸出中的影片作業都已進入最終狀態,例如 completedfailedexpired。請使用固定不變的 custom_id 值,方便將批次結果對應回內部的鏡頭 ID、剪輯佇列或素材處理流程,再使用傳回的影片 ID 下載最終素材。

維護影片庫

使用 GET /videos 列出你的影片。此端點支援選用的查詢參數,可用於分頁和排序。

curl "https://api.openai.com/v1/videos?limit=20&after=video_123&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" | jq .

使用 DELETE /videos/{video_id} 從 OpenAI 的儲存空間中移除不再需要的影片。

curl -X DELETE "https://api.openai.com/v1/videos/REPLACE_WITH_YOUR_VIDEO_ID" \
  -H "Authorization: Bearer $OPENAI_API_KEY" | jq .