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 基于多年的多模态扩散研究,并使用多样化的视觉数据进行训练,将对三维空间、运动和场景连贯性的深刻理解融入文本到视频生成。
Videos API 首次向开发者开放这些能力,让您能够以编程方式创建、延长、编辑和管理视频。
您可以使用它来:
- 根据提示创建新视频。
- 使用参考图像引导生成。
- 在多次生成中复用角色素材,增强视觉一致性。
- 通过视频延长功能续接已完成的片段。
- 对现有视频进行有针对性的编辑。
- 下载已完成的视频及配套素材。
- 通过批处理 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}端点,直到状态变为 completed;也可以采用更高效的方式,使用 Webhook(请参阅下方的 Webhook 部分),在作业完成时自动收到通知。 -
作业进入
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视频。
与较短的 720p 或 480p 渲染相比,时长较长或分辨率为 1080p 的任务可能需要明显更长的时间才能完成,因此设计面向用户的流程时,应考虑更高的延迟。
护栏与限制
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"
}
使用 Webhook 接收通知
您可以注册 Webhook,在视频生成完成或失败时自动接收通知,无需反复使用 GET 轮询任务状态。
您可以在 Webhook 设置页面配置 Webhook。任务结束时,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请求(包括批处理请求)中,使用 JSON 对象作为input_reference的值。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 不同。参考图像用于引导
单次生成的起始帧,而角色素材可以在
后续的视频请求中重复使用。
向 POST /v1/videos/characters 上传一段 MP4 短片来创建角色,然后在创建视频时,将返回的角色 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 .












提示: “她转过身微笑,然后缓缓走出画面。”
提示: “冰箱门打开了。一只可爱、胖乎乎的紫色怪物从里面走出来。”
提示: “将怪物的颜色改为橙色。”
提示: “紧接着,第二只怪物走了出来。”