sora

Sora 视频生成技能

为当前项目创建或管理 Sora 视频任务（产品演示、营销短片、电影感镜头、社交媒体短片、UI 模型）。默认使用 sora-2，并通过结构化提示词增强来优化效果；确定性运行时优先使用捆绑的 CLI。注意：$sora 是提示词中的技能标签，不是 shell 命令。

使用场景

• 根据提示词生成新的视频片段
• 从简短的非人类源视频创建可复用的角色参考
• 通过有针对性的提示词更改来编辑已生成的视频
• 使用续写提示词延长已完成的视频
• 查询状态、列出任务或下载资源（视频／缩略图／精灵图）
• 立即运行本地多任务队列，或规划用于离线渲染的正式 Batch API 提交

决策树

• 如果用户有一段想在多个镜头中重复使用的简短非人类参考视频 → create-character
• 如果用户有已完成的视频，并希望续接下一个节拍／后续内容 → extend
• 如果用户有已完成的视频，并希望在保留镜头的同时进行有针对性的更改 → edit
• 如果用户有视频 ID，并需要查询状态或获取资源 → status、poll 或 download
• 如果用户需要在 Codex 中立即生成大量视频 → create-batch（本地分发，不是 Batch API）
• 如果用户需要为离线处理或工作室流水线生成大量视频 → 使用 references/video-api.md 中描述的官方 Batch API 流程
• 其他情况 → create（如果用户希望一步获得可用资源，则使用 create-and-poll）

工作流

1. 判断意图：create、create-character、edit、extend、status/download、本地队列或官方 Batch API。
2. 收集输入：提示词、模型、尺寸、时长、任何图像参考以及任何角色 ID。
3. 优先使用 CLI 增强标志（--use-case、--scene、--camera 等），而不是手动编写冗长的结构化提示词。如果已有结构化提示词文件，则传入 --no-augment。
4. 使用合理的默认值运行捆绑的 CLI（scripts/sora.py）。对于较长的提示词，优先使用 --prompt-file，以避免 shell 转义问题。
5. 对于异步任务，轮询直至进入终态（或使用 create-and-poll）。
6. 下载资源（视频／缩略图／精灵图），并在 URL 过期前保存到本地。
7. 如果用户希望多个镜头保持连续性，先创建角色资源，然后在后续的 create 调用中引用这些资源。
8. 如果用户想迭代已完成的镜头，优先使用 edit；如果他们想让镜头在时间上继续延伸，则优先使用 extend。
9. 每次迭代只进行一项有针对性的更改。

身份验证

• 发起实时 API 调用必须设置 OPENAI_API_KEY。

如果缺少该密钥，请向用户提供以下步骤：

1. 在 OpenAI 平台 UI 中创建 API 密钥：https://platform.openai.com/api-keys
2. 在其系统中将 OPENAI_API_KEY 设置为环境变量。
3. 如有需要，可提供指导，帮助其在操作系统／shell 中设置环境变量。

• 切勿要求用户在聊天中粘贴完整密钥。请他们在本地设置，并在准备就绪后确认。

默认设置与规则

• 默认模型：sora-2（如需更高保真度，请使用 sora-2-pro）。
• 默认尺寸：1280x720。
• 默认时长：4（允许的值："4"、"8"、"12"、"16"、"20"）。
• 始终通过 API 参数设置尺寸和时长；提示词中的文字不会改变它们。
• 1920x1080 和 1080x1920 必须使用 sora-2-pro。
• 每次生成最多使用两个角色。
• 使用 OpenAI Python SDK（openai 包）。如果高级 SDK 辅助工具落后于最新的 Sora 指南，请使用官方 SDK 内的低级 client.post/get/delete，不要使用独立的 HTTP 代码。
• 进行任何实时 API 调用前，必须确保已设置 OPENAI_API_KEY。
• 如果 uv 缓存权限出错，请设置 UV_CACHE_DIR=/tmp/uv-cache。
• 输入参考图像必须为 jpg/png/webp 格式，且尺寸应与目标尺寸一致。
• JSON input_reference 对象使用 file_id 或 image_url；上传文件路径时使用 multipart。
• 下载 URL 约 1 小时后过期；请将素材复制到自己的存储空间。
• 批量生成的视频在批次完成后最多可下载 24 小时。
• scripts/sora.py 中的 create-batch 是本地并发队列，不是官方 Batch API。
• 优先使用随附的 CLI，除非用户要求，否则绝不修改 scripts/sora.py。
• Sora 可以生成音频；如果用户要求配音/音频，请在 Audio: 和 Dialogue: 行中明确说明，并保持简短。

API 限制

• 模型仅限 sora-2 和 sora-2-pro。
• 访问 Sora 模型的 API 需要经过组织验证的账户。
• 必须通过 seconds 参数设置时长，目前支持 4、8、12、16 和 20。
• 角色上传目前最适合使用 16:9 或 9:16、720p-1080p 的短时长（2-4 秒）非人类 MP4 视频。
• 每次扩展最多可增加 20 秒；每个源视频最多扩展六次，总时长最长为 120 秒。
• 扩展目前不支持角色或图像参考。
• 此技能支持按 ID 编辑已生成的视频。
• 官方 Batch API 目前仅支持 POST /v1/videos，且请求体必须为 JSON，而不是 multipart 上传。
• 输出尺寸受模型限制（请参阅 references/video-api.md 了解支持的尺寸）。
• 视频创建为异步操作；下载前必须轮询，直到任务完成。
• 速率限制因使用层级而异（不要列出具体限制）。
• API 会强制执行内容限制（请参阅下方的内容保护措施）。

内容保护措施（必须执行）

• 内容仅限适合 18 岁以下受众观看。
• 不得使用受版权保护的角色或音乐。
• 不得出现真实人物（包括公众人物）。
• 包含人脸的人物图像会被拒绝。
• 此技能中的角色上传仅适用于非人类对象。

提示词扩充

将提示词重新整理为结构化、面向制作的规范。仅明确隐含的细节；不要臆造新的创作要求。

模板（仅包含相关行）：

Use case: <where the clip will be used>
Primary request: <user's main prompt>
Scene/background: <location, time of day, atmosphere>
Subject: <main subject>
Action: <single clear action>
Camera: <shot type, angle, motion>
Lighting/mood: <lighting + mood>
Color palette: <3-5 color anchors>
Style/format: <film/animation/format cues>
Timing/beats: <counts or beats>
Audio: <ambient cue / music / voiceover if requested>
Text (verbatim): "<exact text>"
Dialogue:
<dialogue>
- Speaker: "Short line."
</dialogue>
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

扩充规则：

• 保持简短；仅补充用户已暗示或在其他位置提供的细节。
• 对于编辑，明确列出不变项（“镜头保持不变，仅更改 X”）。
• 对于基于角色的镜头，在提示词中逐字提及角色名称。
• 如果缺少任何会影响成功的关键信息，请提问；否则继续处理。
• 如果向 CLI 传入结构化提示词文件，请添加 --no-augment，避免工具再次包装提示词。

示例

生成示例（单个镜头）

Use case: product teaser
Primary request: a close-up of a matte black camera on a pedestal
Action: slow 30-degree orbit over 4 seconds
Camera: 85mm, shallow depth of field, gentle handheld drift
Lighting/mood: soft key light, subtle rim, premium studio feel
Constraints: no logos, no text

编辑示例（不变项）

Primary request: same shot and framing, switch palette to teal/sand/rust with warmer backlight
Constraints: keep the subject and camera move unchanged

角色一致性示例

Primary request: Mossy, a moss-covered teapot mascot, hurries through a lantern-lit market at dusk
Camera: cinematic tracking shot, 35mm, shoulder height
Lighting/mood: warm dusk practicals, soft haze
Constraints: keep Mossy’s silhouette and moss texture consistent across the shot

提示词最佳实践（简要列表）

• 每个镜头只安排一个主要动作和一次摄像机移动。
• 使用次数或节拍说明时间安排（“走两步，停顿，转身”）。
• 处理 UI 或屏幕文字时，保持文字简短，并锁定摄像机。
• 出现伪影（闪烁、抖动、快速移动）时，添加简短的避免事项说明。
• 较短的提示词更有创意；较长的提示词控制力更强。
• 将对话放在专门的区块中；对于 4-8 秒的片段，每句台词都要简短。
• 使用上传的角色 ID 时，逐字提及角色名称。
• 编辑时明确说明不变项（保持相同镜头、相同摄像机移动）。
• 针对性修改优先使用 edit，延续时间线优先使用 extend。
• 后续每次只做一项修改，以保持连贯性。

按素材类型提供的指南

当请求涉及特定成品时，请使用这些模块。它们提供了针对性的模板和默认设置。

• 电影镜头：references/cinematic-shots.md
• 社交广告：references/social-ads.md

CLI + 环境说明

• CLI 命令 + 示例：references/cli.md
• API 参数快速参考：references/video-api.md
• 提示词指南：references/prompting.md
• 提示词示例：references/sample-prompts.md
• 故障排除：references/troubleshooting.md
• 网络/沙盒提示：references/codex-network.md

参考索引

• references/cli.md：如何通过 scripts/sora.py 执行 create/edit/extend/create-character/poll/download/local-queue 流程。
• references/video-api.md：API 级参数（模型、尺寸、时长、角色、编辑、扩展、官方 Batch API）。
• references/prompting.md：提示词结构、角色连贯性、编辑和扩展指南。
• references/sample-prompts.md：可直接复制粘贴的提示词方案（仅包含示例，不含额外理论）。
• references/cinematic-shots.md：电影感镜头模板。
• references/social-ads.md：短篇社交广告节拍模板。
• references/troubleshooting.md：常见错误及修复方法。
• references/codex-network.md：网络/审批故障排除。