---
name: "sora"
description: "当用户要求通过使用捆绑的 CLI（`scripts/sora.py`）通过 OpenAI 的视频 API 生成、混音、轮询、列表、下载或删除 Sora 视频时使用，包括诸如生成 AI 视频、使用 Sora、视频混音、视频混音、下载视频/缩略图/精灵表和批量视频生成等请求；需要 `OPENAI_API_KEY` 和 Sora API 访问权限。"
---

# Sora 视频生成技能

为当前项目创建或管理短视频剪辑（产品演示、营销点、电影镜头、UI 模型）。默认为 `sora-2` 和结构化提示增强工作流程，并且更喜欢捆绑的 CLI 以实现确定性运行。注意：`$sora` 是提示中的技能标签，而不是 shell 命令。

## 何时使用
- 从提示生成新的视频剪辑
- 通过 ID 混音现有视频
- 轮询状态、列出作业或下载资产（视频/缩略图/精灵表）
- 批量运行（多个提示或变体）

## 决策树（创建 vs 混音 vs 状态/下载 vs 批量）
- 如果用户有**视频 id**并想要更改 → **混音**
- 如果用户有**视频 id**并想要状态或资产 → **状态/轮询/下载**
- 如果用户需要许多提示/资产 → **创建-批量**
- 如果用户要求使用小更改（相同镜头、不同主题/细节）的两个版本 → **创建**基础，然后**混音**以获取变体
- 否则 → **创建**（或如果他们需要在一个步骤中准备好的资产，则**创建并轮询**）

## 工作流程
1. 确定意图：创建 vs 混音 vs 状态/下载 vs 批量。
2. 收集输入：提示、模型、大小、秒数以及任何输入参考图像。
3. 如果是批量：在 tmp/ 下编写临时 JSONL（每行一个作业），运行一次，然后删除 JSONL。
4. 更喜欢 CLI 增强标志（`--use-case`、`--scene`、`--camera` 等）而不是预先编写结构化提示。如果您已经生成了结构化提示文件，请传递 `--no-augment` 以避免双重包装。
5. 使用合理的默认值运行捆绑的 CLI（`scripts/sora.py`）（见 references/cli.md）。对于长提示，更喜欢 `--prompt-file` 以避免 shell 转义问题；如果提示已经结构化，则配对 `--no-augment`。
6. 对于异步作业，轮询直到完成（或使用创建并轮询）。
7. 下载资产（视频/缩略图/精灵表）并在本地保存。
8. 删除调用期间创建的中间文件（例如 `prompt.txt`、`remix_job.json`、临时 JSONL）。如果沙盒阻止 `rm`，请跳过清理或在不报错的情况下截断文件。
9. 每个提示使用单一目标更改进行迭代。

## 身份验证

- 必须设置 `OPENAI_API_KEY` 才能进行实时 API 调用。

如果缺少密钥，请为用户提供这些步骤：
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"作为字符串）。
- 始终通过 API 参数设置大小和秒数；散文不会更改它们。
- 对所有 API 调用使用 OpenAI Python SDK（`openai` 包）；不要使用原始 HTTP。
- 在任何实时 API 调用之前要求 `OPENAI_API_KEY`。
- 如果 uv 缓存权限失败，请设置 `UV_CACHE_DIR=/tmp/uv-cache`。
- 输入参考图像必须是 jpg/png/webp 并且应该匹配目标大小。
- 下载 URL 在大约 1 小时后过期；将资产复制到您自己的存储。
- 更喜欢捆绑的 CLI 并且**永远不要修改** `scripts/sora.py`，除非用户要求。
- Sora 可以生成音频；如果用户要求配音/音频，请在 `Audio:` 和 `Dialogue:` 行中明确指定它并保持简短。

## API 限制

- 模型限制为 `sora-2` 和 `sora-2-pro`。
- 访问 Sora 模型需要经过组织验证的帐户。
- 持续时间限制为 4/8/12 秒，必须通过 `seconds` 参数设置。
- API 期望 `seconds` 作为字符串枚举（"4"、"8"、"12"）。
- 输出大小受模型限制（有关支持的大小，请参阅 `references/video-api.md`）。
- 视频创建是异步的；您必须在下载之前轮询完成。
- 速率限制按使用层级应用（不要列出具体限制）。
- API 强制执行内容限制（见下面的防护栏）。

## 防护栏（必须强制执行）

- 仅适合 18 岁以下受众的内容。
- 没有版权字符或受版权保护的音乐。
- 没有真人（包括公众人物）。
- 带有人脸的输入图像被拒绝。

## 提示增强

将提示重新格式化为结构化的、面向生产的规范。仅使隐含细节显式化；不要发明新的创意要求。

模板（仅包括相关行）：
```
用例：<剪辑将在哪里使用>
主要请求：<用户的主要提示>
场景/背景：<位置、一天中的时间、氛围>
主题：<主要主题>
行动：<单个明确的行动>
相机：<镜头类型、角度、运动>
灯光/情绪：<灯光 + 情绪>
调色板：<3-5 种颜色锚点>
风格/格式：<电影/动画格式提示>
节拍/节拍：<计数或节拍>
音频：<环境提示 / 音乐 / 如果请求则配音>
文本（逐字）："<精确文本>"
对话：
<对话>
- 说话人："简短行。"
</对话>
约束：<必须保留/必须避免>
避免：<负面约束>
```

增强规则：
- 保持简短；仅添加用户已经暗示或别处提供的细节。
- 对于混音，明确列出变体（"相同镜头、仅更改 X"）。
- 如果任何关键细节缺失并阻止成功，请提问；否则继续。
- 如果您将结构化提示文件传递给 CLI，请添加 `--no-augment` 以避免工具重新包装它。

## 示例

### 生成示例（单个镜头）
```
用例：产品预告
主要请求：在基座上对黑色相机的特写，在 4 秒内缓慢 30 度轨道
行动：缓慢 30 度轨道，持续 4 秒
相机：85mm、浅景深、轻微的手持漂移
灯光/情绪：柔和主光、微妙边缘、高级工作室感觉
约束：无徽标、无文本
```

### 混音示例（变体）
```
主要请求：相同镜头和取景，将调色板切换为蓝绿色/沙/铁锈色，使用更暖的背光
约束：保持主题和相机移动不变
```

## 提示最佳实践（简短列表）
- 每个镜头一个主要行动 + 一个相机移动。
- 使用计数或节拍进行计时（"两步、暂停、转身"）。
- 保持文本简短并为 UI 或屏幕文本锁定相机。
- 当伪影出现时添加简短的避免行（抖动、快速运动）。
- 更短的提示更具创意；更长的提示更受控。
- 将对话放在专用块中；为 4-8 秒剪辑保持行简短。
- 对于混音，明确说明变体（相同镜头、相同相机移动）。
- 使用单一更改后续进行迭代以保持连续性。

## 按资产类型的指导

当请求针对特定资产时，使用这些模块。它们提供有针对性的模板和默认值。
- 电影镜头：`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` 运行创建/轮询/混音/下载/批量（命令、标志、配方）。
- **`references/video-api.md`**：API 级别旋钮（模型、大小、持续时间、变体、状态）。
- **`references/prompting.md`**：提示结构和迭代指导。
- **`references/sample-prompts.md`**：复制/粘贴提示配方（仅示例；没有额外的理论）。
- **`references/cinematic-shots.md`**：电影镜头的模板。
- **`references/social-ads.md`**：短社交广告节拍的模板。
- **`references/troubleshooting.md`**：常见错误和修复。
- **`references/codex-network.md`**：网络/应用程序故障排除。