Sora 2 / Sora 2 Pro Video CLI
Command-line client for OpenAI's Sora 2 and Sora 2 Pro video generation API, implemented in Python (main.py). Supports creating videos (text-only or image-guided), polling, downloading content, listing, retrieving, deleting, and remixing.
Features
-
Models:
sora-2andsora-2-pro - Create: text prompt, resolution, duration; optional image reference via multipart upload
- Status: retrieve and poll with configurable interval and timeout
- Content: download MP4 upon completion
- Manage: list, delete, remix existing videos
- Resilience: retries and backoff on transient errors; clear JSON errors
-
Auth:
OPENAI_API_KEYenv var; optional.envsupport
*Note: Reference image should be specific size.
Requirements
- Python 3.9+
- Dependencies:
- Standard library only for HTTP
- Optional:
python-dotenvif you want.envloading
Install optional dependency:
pip install python-dotenv
Environment and Auth
Set your OpenAI API key as an environment variable or in a .env file at the project root.
export OPENAI_API_KEY="sk-..."
Or create a .env file:
echo 'OPENAI_API_KEY=sk-...' > .env
You can also pass --api-key to any command to override the environment.
Quick Start
Create a 4-second 720p clip with Sora 2:
python main.py create \
--model sora-2 \
--prompt "A cat does a backflip" \
--size 1280x720 \
--seconds 4
Create an image-guided clip (first frame from an image):
python main.py create \
--model sora-2-pro \
--prompt "Logo reveal with mist" \
--size 1280x720 \
--seconds 4 \
--input-reference assets/worker.png
Poll until completion and download when ready:
python main.py poll vid_123 --download -o output.mp4
Download content directly:
python main.py download vid_123 -o output.mp4
List, retrieve, and delete:
python main.py list --limit 10
python main.py retrieve vid_123
python main.py delete vid_123
Remix an existing video with a new prompt:
python main.py remix vid_123 \
--prompt "Change the background to a starry night sky." \
--size 1280x720 \
--seconds 8
Arguments and Validation
-
Models:
sora-2,sora-2-pro -
Durations:
4,8,12seconds -
Sizes:
-
sora-2:1280x720,720x1280 -
sora-2-pro:1280x720,720x1280,1792x1024,1024x1792
-
Invalid combinations will produce a helpful error message before the request is sent.
Base URL Override
Defaults to https://api.openai.com. Override with --base-url if you need a different API host.
python main.py create --base-url https://api.openai.com --model sora-2 ...
Exit Codes
-
0: success -
1: API or validation error -
124: poll timed out
Troubleshooting
- 400 errors: verify
model,size,seconds, and that prompts follow content policy - 401/403: ensure
OPENAI_API_KEYis set and valid - 429: client retries with backoff; consider lowering RPM or waiting
- Multipart image: ensure the path exists and is a supported image type
Notes
- Pricing and access to Sora 2 / Pro depend on your OpenAI account and tier.
- For long-running workflows, prefer
pollwith--downloador set up webhooks in your OpenAI account (when available) to avoid polling.
Top comments (0)