使用 Python 调用 Sora 2 API：完整指南与示例

开始使用 OpenAI API

首先，我们需要创建一个 OpenAI 账户并生成 API 密钥。为此，请前往他们的API 密钥页面，然后在右上角点击 "Create new secret key"。

此密钥用于向 OpenAI API 发起请求。我们将它保存在与编写 Python 脚本相同文件夹下名为 .env 的文件中。请务必妥善保管该密钥，因为任何人都可以用它通过您的账户与 API 交互。

将 API 密钥按以下格式粘贴到 .env 文件中：

OPENAI_API_KEY=<paste_api_key_here>技术支持

请注意，使用 API 并非免费，因此需要先为账户充值，才能使用 Sora 2 生成视频。供参考，以下是 Sora 2 的每秒定价：

使用 Python 生成 Sora 2 视频

本教程的所有代码可在此 GitHub 仓库找到。

要在 Python 中与 OpenAI API 通信，我们将使用 openai 包。请注意，由于 Sora 刚加入 API，需要使用该包的较新版本。

我们可以使用以下命令安装它（或在已安装的情况下升级到最新版本）：

pip install --upgrade openai技术支持

在与 .env 文件同一文件夹下创建一个名为 generate_video.py 的新脚本。

第一步是导入必要的包。我们将使用：

• os：内置包，用于与操作系统交互；
• openai：OpenAI 官方包，用于与其 API 交互；
• dotenv：内置包，便于从 .env 文件加载环境变量。本例中，我们用它来加载 OpenAI API 密钥。

import os
from openai import OpenAI 
from dotenv import load_dotenv技术支持

接下来加载 .env 文件：

load_dotenv()
API_KEY = os.getenv("OPENAI_API_KEY")技术支持

在将 API 密钥加载到内存后，我们可以初始化 OpenAI 客户端，以便向 OpenAI API 发起请求。我们使用 os 库来加载 API 密钥：

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

最后，我们使用客户端的 videos.create 函数生成视频：

video = client.videos.create(
    prompt="A cat and a dog dancing",
)
print(video.id)技术支持

当我们请求生成视频时，不会立刻得到视频，因为生成需要相当长的时间。这意味着 video 变量并不是视频本身，而是一个包含视频生成任务信息的对象。

这就是我们打印视频标识符的原因。接下来我们将用到它来：

1. 跟踪视频生成的进度。
2. 获取视频。

我们将在下文详细解释这两个步骤。

以下是我得到的结果：

跟踪视频进度

我们可以将任务标识符传给 videos.retrieve() 函数来获取任务状态，如下所示：

job = client.videos.retrieve(job_id)
status = job.status
progress = job.progress
print(f"Status: {status}, {progress}%")技术支持

只有当进度达到 100% 时，我们才能下载视频。为方便起见，我们构建了一个函数 wait_for_video_to_finish()，用于监控任务状态直至完成：

def wait_for_video_to_finish(video_id, poll_interval=5, timeout=600):
    """
    Poll status until the video is ready or timeout is reached.
    Returns the final job info.
    """
    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    elapsed = 0  # Keep track of the elapsed time
    while elapsed < timeout:
        job = client.videos.retrieve(video_id)
        status = job.status
        progress = job.progress
        print(f"Status: {status}, {progress}%")
        if status == "completed":
            return job
        if status == "failed":
            raise RuntimeError(f"Failed to generate the video: {job.error.message}") 
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise RuntimeError("Polling timed out")技术支持

该函数有三个参数：

• video_id：我们要跟踪的视频标识符。
• poll_interval：每次跟踪请求之间等待的秒数。
• timeout：最长等待的秒数。

该函数会定期检查视频状态，直到完成或轮询时间耗尽为止。

下载视频

既然我们已经可以跟踪视频生成过程，接下来只需要在生成完成后将其下载。我们可以使用 videos.download_content() 函数实现。

下面是一个实现该功能的函数：

def download_video(video_id):
    client = get_client()
    response = client.videos.download_content(
        video_id=video_id,
    )
    video_bytes = response.read()
    with open(f"{video_id}.mp4", "wb") as f:
        f.write(video_bytes)技术支持

完整的 Sora 视频生成工作流

我们可以将这些步骤组合起来，构建一个使用 Sora 的视频生成工作流：

prompt = "A cat and a dog dancing"
video = client.videos.create(
    prompt="A cat and a dog dancing",
)
video_id = video.id
print(f"Started generating video with id {video_id}")
wait_for_video_to_finish(video_id)
download_video(video_id)技术支持

设置视频尺寸和时长

上面的脚本仅使用文本提示来生成视频。不过，OpenAI Sora 2 API 还提供了其他选项，例如：

• model：用于生成视频的模型。默认是 sora-2。
• resolution：视频的尺寸。默认尺寸为 720x1280。
• duration：视频的时长（秒）。默认时长为 4 秒。

下面的表格展示了在不同模式下所有可能的取值（加粗的是默认值）：

为便于使用脚本，我们可以利用内置包 argparse，让用户为各参数指定取值。

以下是使用 argparse 设置 prompt 和 model 参数的示例：

parser = argparse.ArgumentParser()
parser.add_argument(
    "--prompt", # Name of the argument
    required=True, # Specify that the argument is required
    help="The video prompt.", # Helper text
)
parser.add_argument(
    "--model",
    default="sora-2", # Specify a default value for the argument
    choices=["sora-2", "sora-2-pro"], # Specify a list of possible values for the argument
    help="Model to use (sora-2 or sora-2-pro).",
)技术支持

要加载参数，我们调用 parse_args() 方法，如下所示：

args = parser.parse_args()
prompt = args.prompt
model = args.model技术支持

GitHub 仓库中的 generate_video_pipeline.py 脚本将我们学到的所有内容整合成了一个可用 Sora 2 生成视频的脚本。

以下是在终端中按特定参数运行它的示例：

python generate_video_pipeline.py --prompt "A family of dogs driving a car" --model sora-2-pro  --size 1280x720 --seconds 8技术支持

结果如下：

Sora 2 API 提示词技巧

OpenAI 提供了Sora 2 的完整提示词指南。

构建优质 Sora 2 提示词的核心思路包括：

• 在细节与自由之间取得平衡：具体的提示能提供可控性；简洁的提示能激发创造力。
• 在 API 中设置参数：明确指定模型（sora-2 或 sora-2-pro）、分辨率和片段时长。
• 以“镜头”来思考：描述机位构图、光线、主体，以及每个镜头一个清晰动作。
• 具象且具体：“霓虹灯下的湿漉漉柏油路”胜过“美丽的街道”。
• 保持运动简单：一个主体动作 + 一个镜头运动往往效果最佳。
• 光线：为保持一致性，定义光质、方向与配色。
• 使用图像参考：加入视觉输入以锚定风格与构图。
• 对白：台词简短自然；标注清晰；每个片段内数量有限。
• 使用 Remix 迭代：一次只调整一个元素（光线、镜头、配色），以获得精细控制。

他们将这些想法整合成如下提示词模板：

[Prose scene description in plain language. Describe characters, costumes, scenery, weather and other details. Be as descriptive to generate a video that matches your vision.]
Cinematography:
Camera shot: [framing and angle, e.g. wide establishing shot, eye level]
Mood: [overall tone, e.g. cinematic and tense, playful and suspenseful, luxurious anticipation]
Actions:
- [Action 1: a clear, specific beat or gesture]
- [Action 2: another distinct beat within the clip]
- [Action 3: another action or dialogue line]
Dialogue:
[If the shot has dialogue, add short natural lines here or as part of the actions list. Keep them brief so they match the clip length.]技术支持

在终端中输入很长的提示词不太方便。为改善体验，我们可以修改脚本：当提示词以 .txt 结尾时，脚本将假定用户提供的是包含提示词的文本文件路径。

我们可以这样更新脚本以支持该功能：

...
args = parser.parse_args()
prompt = args.prompt
if prompt.endswith(".txt"):
    with open(prompt, "rt") as f:
        prompt = f.read()
video_id = generate_video(prompt, args.model, args.size, args.seconds)
...技术支持

为测试这一点，我在同一文件夹中创建了名为 prompt.txt 的文件，内容如下：

A polite green alien wearing a beret struggles to order croissants in broken French at a bustling Paris café.

Cinematography:
Camera shot: eye-level shot, warm morning light
Mood: whimsical and awkward
Actions:
The alien studies the pastry display, fascinated.
It points to the baguette, then accidentally eats the napkin.
The waiter shrugs, unfazed, and brings it another napkin.
Dialogue:
Alien (content): “Très… chewy.”技术支持

要生成视频，我们在 --prompt 参数中提供 prompt.txt：

python generate_video_pipeline.py --prompt prompt.txt --model sora-2-pro  --size 1280x720 --seconds 8技术支持

视频如下：

可以看到，它并未完全遵循提示词。根据我在 AI 视频模型上的经验，制作若干更简单的视频并将它们拼接，往往能得到更好的效果。

然而，要做到这一点，我们需要确保视频之间保持一致。我们可以通过向模型提供参考图像实现一致性。接下来我们就来学习这个。

基于图像生成 Sora 2 视频

要基于图像生成视频，我们使用input_reference 参数。

以下代码片段展示了如何加载图像并将其作为参考提供给模型：

f = open("image_reference.jpeg", "rb")

# Generate the video
video = client.videos.create(
    prompt="The two people walk away from each other.",
    input_reference=f
)

f.close()

wait_for_video_to_finish(video.id)
download_video(video.id)技术支持

GitHub 仓库中的脚本 generate_video_with_reference.py提供了一个完整可用的示例。对该参考图像执行时，我们得到如下结果：

要使参考图像生效，其尺寸需要与请求生成视频时的尺寸一致。

我们可以使用 Pillow 包在提供给模型之前自动调整参考图像的大小。但请注意，如果原图的纵横比差异很大，图像会被拉伸变形，生成的视频效果也可能不佳。

安装命令如下：

pip install Pillow技术支持

sora.py 脚本提供了一个 generate_video() 函数实现，对我们之前的代码进行了适配：当提供了图像时，会自动调整图像大小。

generate_video_pipeline_reference.py 脚本展示了我们如何将参考参数加入视频生成脚本中。

以下是我们刚实现的自动调整大小功能，从一张照片生成的示例：

使用视频参考

我们构建的脚本已准备好同时处理视频和图像参考。不过，每当我尝试在提供一个视频作为参考的情况下生成视频时，都会遇到如下错误：

Video inpaint is not available for your organization技术支持

根据他们的论坛，这似乎是一个常见问题，这表明该功能尚未对所有 API 用户开放。我们还需要再等等才能使用它。

其他限制

我在使用 Sora 2 的过程中，经常遇到 Sora 拒绝生成视频的情况，提示是请求被审核系统拦截：

RuntimeError: Video generation failed: Your request was blocked by our moderation system.技术支持

我理解此类系统需要强力的内容审核，因为如果允许用户随意生成任何视频，可能会造成很大危害。不过我感觉该审核算法仍需打磨，因为它拦截了我大多数请求，导致我不得不放弃最初的想法。

我尝试转换为视频的照片并无敏感内容或版权问题，且所有图片均为我本人所有。而且该错误也未说明被拦截的具体原因。

这一问题出现非常频繁，使我无法产出有意义的内容。

结语

Sora 2 为 AI 驱动的视频生成带来了令人兴奋的新可能性，借由其通过 OpenAI API 提供，现今各类背景的开发者都能将这些前沿工具集成进自己的 Python 工作流。

通过本教程，您已掌握用简单提示词创建自定义视频的基础，能够用高级参数微调结果，并利用图像参考提升一致性。随着 API 不断演进，更多功能（包括强大的视频到视频能力）将陆续开放，进一步扩展您的创作工具箱。

无论您是在尝试有趣的提示词、构建复杂的分镜，还是开发下一代多媒体应用，Sora 2 都能为您的灵感赋予生命。也推荐查看我们的Meta 全新 SAM3 模型指南。