sora-video
AI video generation skill for Stomme AI customers using OpenAI's Sora 2 API. Wraps a production-grade Python CLI with marketing-focused prompt templates for business use cases.
Prerequisites
OpenAI API Key (Required)
Customers need their own
OPENAI_API_KEY from OpenAI's platform:
- 1. Go to platform.openai.com/api-keys
- Create a new API key with video generation permissions
- Set it as an environment variable: INLINECODE1
- Ensure your OpenAI organization has Sora API access enabled
Important: A ChatGPT Pro/Plus subscription does NOT provide API access to Sora. You need a separate API key with pay-per-use billing from platform.openai.com.
Python + uv
The CLI requires Python 3.10+ and uses
uv for dependency management (auto-installs the
openai SDK):
CODEBLOCK0
Pricing Guide
| Model | Duration | Approximate Cost |
|---|
| sora-2 | 4s | ~$0.10 |
| sora-2 |
8s | ~$0.20 |
| sora-2 | 12-16s | ~$0.30 |
| sora-2 | 20s | ~$0.40 |
| sora-2-pro | 4s | ~$0.25 |
| sora-2-pro | 8s | ~$0.40 |
| sora-2-pro | 12-16s | ~$0.50 |
| sora-2-pro | 20s | ~$0.60 |
Costs are per video generation attempt. Failed or cancelled jobs are not billed. Prices are approximate and may change — check OpenAI's pricing page for current rates.
When to Use
- - Generate product demo videos from text descriptions
- Create social media ad clips (Instagram, TikTok, LinkedIn)
- Produce brand identity spots and launch teasers
- Edit or extend existing generated videos
- Create reusable non-human character references for brand mascots
- Batch-generate multiple video variants for A/B testing
Decision Tree
- - Product demo → use
templates/product-demo.md template + INLINECODE5 - Social ad → use
templates/social-ads.md template + create (4-8s) - Brand spot → use
templates/brand-spots.md template + create or INLINECODE10 - Launch teaser → use
templates/launch-teaser.md template + INLINECODE12 - Character-based shots →
create-character first, then create with character IDs - Edit existing video →
edit (one targeted change per iteration) - Extend existing video →
extend (continue timeline) - Batch variants →
create-batch with JSONL input - Check status →
status or INLINECODE19 - Download assets →
download (video/thumbnail/spritesheet)
Workflow
- 1. Select a template from
templates/ matching the use case (or write a custom prompt). - Run the CLI via
scripts/sora.py with appropriate flags. - For async jobs, poll until completion (or use
create-and-poll). - Download assets before URLs expire (~1 hour).
- Iterate with
edit (targeted changes) or extend (timeline continuation).
CLI Quick Start
Set the CLI path:
CODEBLOCK1
Generate a video
CODEBLOCK2
Generate and auto-download
CODEBLOCK3
Dry-run (no API call)
CODEBLOCK4
Full CLI reference: INLINECODE26
Authentication
- -
OPENAI_API_KEY must be set for live API calls. - Never ask customers to paste their full key in chat — have them set it locally.
- If key is missing, guide them to platform.openai.com/api-keys.
- ChatGPT subscription OAuth tokens do NOT work (missing
api.videos.* scopes).
Models & Defaults
- - Default model:
sora-2 (fast, flexible) - Premium model:
sora-2-pro (higher fidelity, required for 1080p) - Default size: INLINECODE31
- Default duration:
4 seconds - Allowed durations: 4, 8, 12, 16, 20 seconds
Size Support
| Model | Sizes |
|---|
| sora-2 | 1280x720, 720x1280 |
| sora-2-pro |
1280x720, 720x1280, 1024x1792, 1792x1024, 1920x1080, 1080x1920 |
Prompt Augmentation
The CLI automatically reformats prompts into a structured production spec. Use CLI flags instead of writing long structured prompts:
CODEBLOCK5
If your prompt is already structured, add --no-augment.
Marketing Templates
Ready-to-use prompt templates for common business video needs:
| Template | File | Best For |
|---|
| Product Demos | INLINECODE34 | Product launches, feature showcases |
| Social Ads |
templates/social-ads.md | Instagram, TikTok, LinkedIn clips |
| Brand Spots |
templates/brand-spots.md | Brand identity, company culture |
| Launch Teasers |
templates/launch-teaser.md | Pre-launch hype, coming soon |
Guardrails (Enforced by API)
- - Only content suitable for audiences under 18
- No copyrighted characters or music
- No real people (including public figures)
- Input images with human faces are rejected
- Character uploads are for non-human subjects only
API Limitations
- - Models:
sora-2 and sora-2-pro only - Duration set via
seconds parameter (4, 8, 12, 16, 20) - Max 2 characters per generation
- Extensions: up to 20s each, 6 times max (120s total)
- Extensions do not support characters or image references
- Video creation is async — must poll for completion
- Download URLs expire after ~1 hour
- Content restrictions enforced server-side
Reference Map
- -
references/cli.md — Full CLI command reference references/video-api.md — API parameters and endpointsreferences/prompting.md — Prompt engineering best practicesreferences/troubleshooting.md — Common errors and fixestemplates/product-demo.md — Product demo prompt templatestemplates/social-ads.md — Social ad prompt templatestemplates/brand-spots.md — Brand identity spot templatestemplates/launch-teaser.md — Launch teaser templates
sora-video
面向Stomme AI客户的AI视频生成技能，使用OpenAI的Sora 2 API。将生产级Python CLI与面向营销的提示模板相结合，适用于商业用例。
前提条件
OpenAI API密钥（必需）
客户需要从OpenAI平台获取自己的OPENAI
APIKEY：
- 1. 访问 platform.openai.com/api-keys
- 创建一个具有视频生成权限的新API密钥
- 将其设置为环境变量：export OPENAIAPI_KEY=sk-...
- 确保您的OpenAI组织已启用Sora API访问权限
重要提示： ChatGPT Pro/Plus订阅不提供Sora的API访问权限。您需要从platform.openai.com获取一个独立的、按使用量计费的API密钥。
Python + uv
CLI需要Python 3.10+，并使用uv进行依赖管理（自动安装openai SDK）：
bash
如果尚未安装uv，请执行以下命令
curl -LsSf https://astral.sh/uv/install.sh | sh
定价指南
| 模型 | 时长 | 大致费用 |
|---|
| sora-2 | 4秒 | ~$0.10 |
| sora-2 |
8秒 | ~$0.20 |
| sora-2 | 12-16秒 | ~$0.30 |
| sora-2 | 20秒 | ~$0.40 |
| sora-2-pro | 4秒 | ~$0.25 |
| sora-2-pro | 8秒 | ~$0.40 |
| sora-2-pro | 12-16秒 | ~$0.50 |
| sora-2-pro | 20秒 | ~$0.60 |
费用按每次视频生成尝试计算。失败或取消的任务不收费。价格为大致估算，可能发生变化——请查看 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，然后使用角色ID执行 create
- 编辑现有视频 → edit（每次迭代进行一项针对性修改）
- 扩展现有视频 → extend（延续时间线）
- 批量变体 → 使用JSONL输入执行 create-batch
- 检查状态 → status 或 poll
- 下载资源 → download（视频/缩略图/精灵图）
工作流程
- 1. 从 templates/ 中选择与用例匹配的模板（或编写自定义提示）。
- 通过 scripts/sora.py 使用适当的标志运行CLI。
- 对于异步任务，轮询直至完成（或使用 create-and-poll）。
- 在URL过期前（约1小时）下载资源。
- 使用 edit（针对性修改）或 extend（时间线延续）进行迭代。
CLI快速入门
设置CLI路径：
bash
export SORA_CLI=/scripts/sora.py
生成视频
bash
uv run --with openai python $SORA_CLI create \
--prompt 大理石表面上高端智能手表的特写 \
--model sora-2 \
--size 1280x720 \
--seconds 8
生成并自动下载
bash
uv run --with openai python $SORA_CLI create-and-poll \
--prompt 无线耳机的产品主镜头 \
--model sora-2-pro \
--size 1920x1080 \
--seconds 4 \
--download \
--out hero.mp4
试运行（不调用API）
bash
python $SORA_CLI create --prompt 测试提示 --dry-run
完整CLI参考：references/cli.md
身份验证
- - 必须设置 OPENAIAPIKEY 才能进行实时API调用。
- 切勿要求客户在聊天中粘贴其完整密钥——让他们在本地设置。
- 如果缺少密钥，引导他们访问 platform.openai.com/api-keys。
- ChatGPT订阅的OAuth令牌无效（缺少 api.videos.* 作用域）。
模型与默认值
- - 默认模型： sora-2（快速、灵活）
- 高级模型： sora-2-pro（更高保真度，1080p必需）
- 默认尺寸： 1280x720
- 默认时长： 4 秒
- 允许的时长： 4、8、12、16、20秒
尺寸支持
| 模型 | 尺寸 |
|---|
| sora-2 | 1280x720、720x1280 |
| sora-2-pro |
1280x720、720x1280、1024x1792、1792x1024、1920x1080、1080x1920 |
提示增强
CLI会自动将提示重新格式化为结构化的生产规范。使用CLI标志而不是编写冗长的结构化提示：
bash
uv run --with openai python $SORA_CLI create \
--prompt 展示中的高端耳机 \
--use-case 产品预告片 \
--scene 暗色工作室，柔和薄雾 \
--camera 85mm，慢速环绕 \
--lighting 柔和主光，温和边缘光 \
--seconds 8
如果您的提示已经结构化，请添加 --no-augment。
营销模板
适用于常见商业视频需求的即用型提示模板：
| 模板 | 文件 | 最佳用途 |
|---|
| 产品演示 | templates/product-demo.md | 产品发布、功能展示 |
| 社交广告 |
templates/social-ads.md | Instagram、TikTok、LinkedIn片段 |
| 品牌宣传片 | templates/brand-spots.md | 品牌形象、公司文化 |
| 发布预告片 | templates/launch-teaser.md | 发布前造势、即将推出 |
安全护栏（由API强制执行）
- - 仅限适合18岁以下观众的内容
- 不得使用受版权保护的角色或音乐
- 不得出现真实人物（包括公众人物）
- 包含人脸的输入图像将被拒绝
- 角色上传仅限非人类主体
API限制
- - 模型：仅限 sora-2 和 sora-2-pro
- 通过 seconds 参数设置时长（4、8、12、16、20）
- 每次生成最多2个角色
- 扩展：每次最多20秒，最多6次（总计120秒）
- 扩展不支持角色或图像参考
- 视频创建为异步操作——必须轮询直至完成
- 下载URL约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 — 发布预告片模板
