sora-video

面向 Stomme AI 客户的 AI 视频生成能力，基于 OpenAI 的 Sora 2 API 构建。该能力封装了一个生产级 Python CLI 工具，并内置面向市场营销场景的提示词模板，专为商业用途优化。

前提条件

OpenAI API 密钥（必需）

客户需自行从 OpenAI 平台获取有效的 OPENAI_API_KEY：

1. 访问 platform.openai.com/api-keys
2. 创建一个具备视频生成权限的新 API 密钥
3. 将其设为环境变量：export OPENAI_API_KEY="sk-..."
4. 确保您的 OpenAI 组织已启用 Sora API 访问权限

重要说明：ChatGPT Pro/Plus 订阅不提供对 Sora 的 API 访问权限。您必须单独在 platform.openai.com 上开通按用量计费的 API 密钥。

Python + uv

该 CLI 工具要求 Python 3.10 或更高版本，并使用 uv 进行依赖管理（自动安装 openai SDK）：

# 如尚未安装 uv，请执行以下命令
curl -LsSf https://astral.sh/uv/install.sh | sh

定价指南

费用按单次视频生成请求计费；失败或取消的任务不收费。以上价格为预估参考，可能变动——请以 OpenAI 官方定价页面为准。

适用场景

• 根据文本描述生成产品演示视频
• 制作社交媒体广告片段（Instagram、TikTok、LinkedIn）
• 制作品牌标识短片与新品发布预告片
• 编辑或延展已生成的视频
• 创建可复用的非人类角色参考，用于品牌吉祥物等场景
• 批量生成多个视频变体，用于 A/B 测试

决策流程图

• 产品演示 → 使用 templates/product-demo.md 模板 + create 命令
• 社交媒体广告 → 使用 templates/social-ads.md 模板 + create 命令（推荐时长：4–8 秒）
• 品牌短片 → 使用 templates/brand-spots.md 模板 + create 或 create-and-poll 命令
• 发布预告片 → 使用 templates/launch-teaser.md 模板 + create-and-poll 命令
• 基于角色的镜头 → 先运行 create-character 创建角色，再在 create 中引用角色 ID
• 编辑已有视频 → 使用 edit 命令（每次仅支持一项针对性修改）
• 延展已有视频 → 使用 extend 命令（延续时间线）
• 批量生成变体 → 使用 create-batch 命令，输入 JSONL 格式文件
• 查询任务状态 → 使用 status 或 poll 命令
• 下载资源 → 使用 download 命令（支持视频 / 缩略图 / 雪碧图）

工作流

1. 从 templates/ 目录中选择匹配业务场景的模板（或自定义提示词）。
2. 通过 scripts/sora.py 执行 CLI，传入相应参数。
3. 对于异步任务，请轮询直至完成（也可直接使用 create-and-poll）。
4. 在下载链接过期前（约 1 小时内）及时下载生成资源。
5. 如需迭代优化，可使用 edit（针对性修改）或 extend（延展时间线）。

CLI 快速入门

设置 CLI 路径：

export SORA_CLI="/scripts/sora.py"

生成视频

uv run --with openai python "$SORA_CLI" create 
  --prompt "大理石台面上的高端智能手表特写" 
  --model sora-2 
  --size 1280x720 
  --seconds 8

生成并自动下载

uv run --with openai python "$SORA_CLI" create-and-poll 
  --prompt "无线耳机产品主视觉镜头" 
  --model sora-2-pro 
  --size 1920x1080 
  --seconds 4 
  --download 
  --out hero.mp4

试运行（不发起 API 请求）

python "$SORA_CLI" create --prompt "测试提示词" --dry-run

完整 CLI 参考文档：references/cli.md

身份验证

• 发起真实 API 调用时，必须设置 OPENAI_API_KEY 环境变量。
• 切勿要求客户在聊天界面中粘贴完整密钥——应引导其在本地配置。
• 若密钥缺失，请指引客户前往 platform.openai.com/api-keys 获取。
• ChatGPT 订阅所关联的 OAuth Token 不可用（缺少 api.videos.* 权限范围）。

模型与默认值

• 默认模型：sora-2（速度快、灵活性高）
• 高级模型：sora-2-pro（画质更高，1080p 输出必需）
• 默认分辨率：1280x720
• 默认时长：4 秒
• 支持时长：4、8、12、16、20 秒

分辨率支持

提示词增强（Prompt Augmentation）

CLI 会自动将原始提示词重构成结构化的制作规范。建议优先使用 CLI 参数，而非手动编写冗长的结构化提示：

uv run --with openai python "$SORA_CLI" create 
  --prompt "高端耳机陈列展示" 
  --use-case "产品预告" 
  --scene "暗调影棚，柔和雾化效果" 
  --camera "85mm 镜头，缓慢环绕运镜" 
  --lighting "柔光主光，轻盈轮廓光" 
  --seconds 8

若您的提示词已是结构化格式，请添加 --no-augment 参数跳过自动增强。

营销模板

开箱即用的提示词模板，覆盖常见商业视频需求：

安全护栏（由 API 强制执行）

• 仅允许面向 18 岁以下受众的适宜内容
• 禁止使用受版权保护的角色或音乐
• 禁止生成真实人物（含公众人物）
• 含真人面部的输入图像将被拒绝
• 上传的角色素材仅限非人类主体

API 限制

• 支持模型仅限：sora-2 和 sora-2-pro
• 视频时长通过 seconds 参数指定（仅支持 4、8、12、16、20 秒）
• 单次生成最多包含 2 个角色
• 延展操作：每次最多延展 20 秒，总计最多延展 6 次（总时长上限 120 秒）
• 延展操作不支持角色或图像参考
• 视频生成为异步操作，需主动轮询确认完成状态
• 下载链接有效期约为 1 小时
• 所有内容限制均由服务端强制执行

参考文档映射表

• references/cli.md — 完整 CLI 命令参考
• references/video-api.md — API 参数与端点说明
• references/prompting.md — 提示词工程最佳实践
• references/troubleshooting.md — 常见错误及解决方案
• templates/product-demo.md — 产品演示提示词模板
• templates/social-ads.md — 社交媒体广告提示词模板
• templates/brand-spots.md — 品牌标识短片提示词模板
• templates/launch-teaser.md — 发布预告片提示词模板