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 基于多年的多模态扩散研究,并使用多样化的视觉数据进行训练,将对三维空间、运动和场景连贯性的深刻理解融入文本到视频生成。

Videos API 首次向开发者开放这些能力,让您能够以编程方式创建、延长、编辑和管理视频。

您可以使用它来:

  • 根据提示创建新视频。
  • 使用参考图像引导生成。
  • 在多次生成中复用角色素材,增强视觉一致性。
  • 通过视频延长功能续接已完成的片段。
  • 对现有视频进行有针对性的编辑。
  • 下载已完成的视频及配套素材。
  • 通过批处理 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} 端点,直到状态变为 completed;也可以采用更高效的方式,使用 Webhook(请参阅下方的 Webhook 部分),在作业完成时自动收到通知。

  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 视频。

与较短的 720p 或 480p 渲染相比,时长较长或分辨率为 1080p 的任务可能需要明显更长的时间才能完成,因此设计面向用户的流程时,应考虑更高的延迟。

护栏与限制

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"
}

使用 Webhook 接收通知

您可以注册 Webhook,在视频生成完成或失败时自动接收通知,无需反复使用 GET 轮询任务状态。

您可以在 Webhook 设置页面配置 Webhook。任务结束时,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 请求(包括批处理请求)中,使用 JSON 对象作为 input_reference 的值。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 不同。参考图像用于引导 单次生成的起始帧,而角色素材可以在 后续的视频请求中重复使用。

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_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 .