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 的算繪時間較長,使用成本也較高,但能產生更精緻、穩定的成果。它最適合高解析度的電影感影像、行銷素材,以及任何對視覺精準度要求嚴格的情境。
如果需要以 1920x1080 或 1080x1920 匯出 1080p 影片,請使用 sora-2-pro。
sora-2 和 sora-2-pro 都支援生成 16 秒及 20 秒的影片。
生成影片
影片生成是 非同步 流程:
-
呼叫
POST /videos端點時,API 會傳回作業物件,其中包含作業的id和初始status。 -
你可以輪詢
GET /videos/{video_id}端點,直到狀態變為已完成;也可以採用更有效率的方式,使用 webhooks(請參閱下方的 webhooks 章節),在作業完成時自動接收通知。 -
作業達到
completed狀態後,你就能使用GET /videos/{video_id}/content取得最終的 MP4 檔案。
啟動算繪作業
首先,呼叫 POST /videos 並提供文字提示詞和必要參數。提示詞用來定義創作的視覺風格與氛圍,包括主體、鏡頭、光線及動作;size 和 seconds 等參數則用來控制影片的解析度與長度。
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 和初始狀態,例如 queued 或 in_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,以1920x1080或1080x1920匯出更高解析度的影片。
較長的影片和 1080p 作業,所需的完成時間可能明顯超過簡短的 720p 或 480p 算繪作業,因此設計使用者操作流程時,請將較長的延遲納入考量。
防護機制與限制
API 會強制執行以下內容限制:
- 僅允許適合未滿 18 歲觀眾的內容(未來將提供可略過此限制的設定)。
- 受著作權保護的角色和音樂將遭拒絕。
- 無法生成真實人物,包括公眾人物。
- 預設會封鎖呈現人類樣貌的角色上傳內容。
- 目前會拒絕包含人臉的輸入圖像。
請確保提示詞、參考圖像和逐字稿符合這些規則,以免生成失敗。
撰寫有效的提示詞
為獲得最佳結果,請描述 鏡頭類型、主體、動作、場景和光線。例如:
- 「遠景鏡頭:一個孩子在綠草如茵的公園裡放紅色風箏,沐浴在黃金時刻的陽光下,鏡頭緩緩向上移動。」
- 「特寫鏡頭:木桌上的咖啡杯冒著熱氣,晨光透過百葉窗灑入,景深效果柔和。」
這樣具體的描述有助於模型產生一致的結果,避免自行添加不必要的細節。如需更進階的提示詞技巧,請參閱我們專為 Sora 2 撰寫的提示詞指南。
監控進度
影片生成需要時間。視模型、API 負載和解析度而定, 單次算繪可能需要數分鐘。
為了有效掌握進度,你可以輪詢 API 以取得最新狀態,或透過 webhook 接收通知。
輪詢狀態端點
使用建立作業時傳回的 ID 呼叫 GET /videos/{video_id}。回應會顯示作業的目前狀態、進度百分比(若有提供),以及任何錯誤。
常見狀態包括 queued、in_progress、completed 和 failed。請以合理的間隔輪詢(例如每 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.completed 或 video.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。此端點會以串流方式傳輸二進位影片資料,並傳回標準內容標頭,因此你可以將檔案直接儲存至磁碟,或透過管線傳送至雲端儲存空間。
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_id或image_url。
圖像的解析度必須與目標影片的解析度(size)相符。
支援的檔案格式為 image/jpeg、image/png 和 image/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) |
|---|---|
下載此圖像 | 提示詞: 「她轉過身微笑,接著緩緩走出畫面。」 |
下載此圖像 | 提示詞: 「冰箱門打開了。一隻可愛、胖嘟嘟的紫色怪獸從裡面走出來。」 |
使用角色維持一致性
角色功能讓你上傳可重複使用的非人類主體,並在多次生成時引用。如果你希望動物、吉祥物或物件在多個鏡頭中保持相同的主要外觀、造型和畫面表現,這個功能會很實用。
目前上傳角色時,以長度 2 至 4 秒、長寬比為
16:9 或 9:16、解析度為 720p 至 1080p 的短片效果最佳。角色來源影片的長寬比
與請求輸出的長寬比相符時,效果最佳。如果長寬比
不同,角色可能會被拉伸或變形。單部影片最多可
包含兩個角色。
角色與 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_id或image_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 狀態時,其輸出中的影片作業都已進入最終狀態,例如 completed、failed 或 expired。請使用固定不變的 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 .












提示詞: 「她轉過身微笑,接著緩緩走出畫面。」
提示詞: 「冰箱門打開了。一隻可愛、胖嘟嘟的紫色怪獸從裡面走出來。」
提示詞: 「將怪物的顏色改成橘色。」
提示詞: 「第二隻怪物緊接著走出來。」