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
2. Create a new API key with video generation permissions
3. Set it as an environment variable: export OPENAI_API_KEY="sk-..."
4. 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):

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

Pricing Guide

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 + create
• Social ad → use templates/social-ads.md template + create (4-8s)
• Brand spot → use templates/brand-spots.md template + create or create-and-poll
• Launch teaser → use templates/launch-teaser.md template + create-and-poll
• 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 poll
• Download assets → download (video/thumbnail/spritesheet)

Workflow

1. Select a template from templates/ matching the use case (or write a custom prompt).
2. Run the CLI via scripts/sora.py with appropriate flags.
3. For async jobs, poll until completion (or use create-and-poll).
4. Download assets before URLs expire (~1 hour).
5. Iterate with edit (targeted changes) or extend (timeline continuation).

CLI Quick Start

Set the CLI path:

export SORA_CLI="<path-to-skill>/scripts/sora.py"

Generate a video

uv run --with openai python "$SORA_CLI" create \
  --prompt "Close-up of a premium smartwatch on marble surface" \
  --model sora-2 \
  --size 1280x720 \
  --seconds 8

Generate and auto-download

uv run --with openai python "$SORA_CLI" create-and-poll \
  --prompt "Product hero shot of wireless earbuds" \
  --model sora-2-pro \
  --size 1920x1080 \
  --seconds 4 \
  --download \
  --out hero.mp4

Dry-run (no API call)

python "$SORA_CLI" create --prompt "Test prompt" --dry-run

Full CLI reference: references/cli.md

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: 1280x720
• Default duration: 4 seconds
• Allowed durations: 4, 8, 12, 16, 20 seconds

Size Support

Prompt Augmentation

The CLI automatically reformats prompts into a structured production spec. Use CLI flags instead of writing long structured prompts:

uv run --with openai python "$SORA_CLI" create \
  --prompt "Premium headphones on display" \
  --use-case "product teaser" \
  --scene "dark studio, soft haze" \
  --camera "85mm, slow orbit" \
  --lighting "soft key, gentle rim" \
  --seconds 8

If your prompt is already structured, add --no-augment.

Marketing Templates

Ready-to-use prompt templates for common business video needs:

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 endpoints
• references/prompting.md — Prompt engineering best practices
• references/troubleshooting.md — Common errors and fixes
• templates/product-demo.md — Product demo prompt templates
• templates/social-ads.md — Social ad prompt templates
• templates/brand-spots.md — Brand identity spot templates
• templates/launch-teaser.md — Launch teaser templates