Sora-2 CLI

A command-line interface for OpenAI's Sora-2 video generation API. Generate high-quality videos from text prompts using the latest OpenAI video generation technology.

Features

• 🎬 Video Generation: Create videos from text prompts using Sora-2
• ⚡ Async Processing: Non-blocking video generation with progress tracking
• 🔄 Retry Logic: Automatic retry with exponential backoff for reliability
• 📊 Progress Tracking: Real-time progress updates during generation
• 🎛️ Flexible Options: Customizable duration, resolution, and other parameters
• 🛡️ Error Handling: Comprehensive error handling and user feedback

Prerequisites

• Python 3.10 or higher
• OpenAI API key with Sora-2 access
• Verified OpenAI organization (required for Sora-2)

Installation

1. Clone the repository:

   git clone https://github.com/tenxsciences/sora2-cli.git
   cd sora2-cli

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -e .

Configuration

API Key Setup

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="sk-proj-your-api-key-here"

Or create a .env file:

echo "OPENAI_API_KEY=sk-proj-your-api-key-here" > .env

Organization Verification

Important: Sora-2 requires organization verification. Complete this step at: https://platform.openai.com/settings/organization/general

Usage

New Workflow: Separate Commands (Recommended)

The CLI now supports three separate commands for better control:

1. Submit Video Generation

# Submit a video generation job (returns immediately with job ID)
sora submit "A serene lake at sunset, cinematic style"

# With custom options
sora submit "Your prompt here" --duration 12 --resolution 1080p --seed 42

2. Poll Status (Continuous Updates)

# Poll job status until completion (shows real-time progress)
sora poll video_68e71929aabc819095603247a3572bc30a3628d70f498e64

# With custom polling interval
sora poll video_68e71929aabc819095603247a3572bc30a3628d70f498e64 --interval 2.0

3. Download Completed Video

# Download a completed video
sora download video_68e71929aabc819095603247a3572bc30a3628d70f498e64

# With custom output file
sora download video_68e71929aabc819095603247a3572bc30a3628d70f498e64 --output-file my_video.mp4

Legacy Commands (Still Available)

Basic Video Generation

# Generate a simple video (legacy - waits for completion)
sora generate "A serene lake at sunset, cinematic style"

# Generate with custom duration and resolution
sora generate "A cat playing with a ball" --duration 12 --resolution 1080p --out cat_video.mp4

Advanced Options

# Full command with all options
sora generate "Your prompt here" \
  --duration 12 \
  --resolution 1080p \
  --seed 42 \
  --out output_video.mp4 \
  --wait

Check Generation Status

# Check status with percentage progress
sora status job_12345

# Check status with full details
sora status job_12345 --verbose

Command Options

Submit Command:

• --duration: Video duration in seconds (4, 8, or 12)
• --resolution: Video resolution (720x1280, 1280x720 for Sora-2; 720x1280, 1280x720, 1024x1792, 1792x1024 for Sora-2 Pro)
• --seed: Random seed for reproducible results

Poll Command:

• --interval: Polling interval in seconds (default: 3.0)

Download Command:

• --output-file: Output file path

Legacy Generate Command:

• --duration: Video duration in seconds (default: 12)
• --resolution: Video resolution (720x1280, 1280x720 for Sora-2; 720x1280, 1280x720, 1024x1792, 1792x1024 for Sora-2 Pro)
• --seed: Random seed for reproducible results
• --out: Output file path
• --wait: Wait for completion and download (default: true)
• --dry-run: Show JSON payload without making request

Status Display

All status commands show:

• ⏳ In Progress: Video is being generated (shows percentage)
• ✅ Completed: Video is ready for download
• ❌ Failed: Generation failed with error details

Example: AI About to Pop

The repository includes an example prompt for generating a darkly satirical AI startup video:

# Generate the example video using JSON config
sora generate-from-json ai-about-to-pop/video.json

# Or generate directly with command line
sora generate "$(cat ai-about-to-pop/prompt.txt)" \
  --duration 12 \
  --resolution 1080p \
  --out ai-about-to-pop/ai_about_to_pop_12s.mp4

Note: Sora-2 only supports durations of 4, 8, or 12 seconds, and specific resolutions:

• Sora-2: Portrait 720x1280, Landscape 1280x720
• Sora-2 Pro: Portrait 720x1280, Landscape 1280x720, Portrait 1024x1792, Landscape 1792x1024

Project Structure

sora2-cli/
├── sora_cli/           # Main CLI package
│   ├── __init__.py     # Package initialization
│   ├── __main__.py     # CLI entry point
│   ├── cli.py          # Command-line interface
│   ├── client.py       # OpenAI API client
│   └── config.py       # Configuration management
├── ai-about-to-pop/    # Example project
│   ├── prompt.txt      # AI comedy video prompt
│   └── video.json      # Video configuration
├── pyproject.toml      # Project configuration
├── requirements.txt    # Dependencies
└── README.md          # This file

API Requirements

OpenAI Account Setup

1. API Key: Get your API key from https://platform.openai.com/account/api-keys
2. Organization Verification: Required for Sora-2 access
3. Billing: Ensure your account has sufficient credits

Model Access

• Sora-2: Requires organization verification
• Other Models: GPT-5, GPT-4o, etc. (for testing)

Recent Improvements

✅ Fixed Issues

• Status Checking: Now uses correct OpenAI API endpoints
• Video Download: Fixed to use proper download_content method
• API Parameters: Duration and resolution parameters now work correctly
• Status Display: Added percentage progress and status icons
• Error Handling: Improved error messages and debugging
• Variable Shadowing: Fixed parameter shadowing in download command

✅ New Features

• Separate Commands: New submit, poll, and download commands for better workflow control
• Immediate Submission: submit command returns job ID immediately without waiting
• Continuous Polling: poll command shows real-time progress until completion
• Separate Download: download command for downloading completed videos
• Progress Tracking: Real-time percentage display during generation
• Status Icons: Visual indicators for different states (⏳ ✅ ❌)
• Verbose Mode: --verbose flag for detailed status information
• Better Error Messages: Clearer error reporting and troubleshooting
• Custom Polling Interval: Configurable polling frequency

Troubleshooting

Common Issues

1. 403 Organization Verification Error

   Error: Your organization must be verified to use the model sora-2
   

   Solution: Complete organization verification at https://platform.openai.com/settings/organization/general

2. 401 Unauthorized Error

   Error: Incorrect API key provided
   

   Solution: Check your API key and ensure it's correctly set

3. Billing Limit Reached

   Error: Billing hard limit has been reached
   

   Solution: Add funds to your OpenAI account

4. Moderation Blocked

   Error: Your request was blocked by our moderation system
   

   Solution: Modify your prompt to be more appropriate for content moderation

Testing API Access

Test your API key with a simple command:

python simple_test.py

Development

Running Tests

# Test API key
python simple_test.py

# Test with dry run
sora generate "test prompt" --dry-run

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Create an issue in this repository
• Check OpenAI documentation: https://platform.openai.com/docs/guides/video-generation
• Verify organization status: https://platform.openai.com/settings/organization/general

Changelog

v0.3.0 (Latest)

• ✅ New Workflow: Added separate submit, poll, and download commands
• ✅ Immediate Submission: submit command returns job ID immediately
• ✅ Continuous Polling: poll command shows real-time progress until completion
• ✅ Separate Download: download command for downloading completed videos
• ✅ Fixed Variable Shadowing: Resolved parameter shadowing in download command
• ✅ Enhanced Documentation: Updated README with new workflow examples
• ✅ Better User Experience: Clean separation of concerns for video generation workflow

v0.2.0

• ✅ Fixed Status Checking: Now uses correct OpenAI API endpoints
• ✅ Fixed Video Download: Proper download_content method implementation
• ✅ Enhanced Status Display: Added percentage progress and status icons
• ✅ Improved Error Handling: Better error messages and debugging
• ✅ Added Verbose Mode: --verbose flag for detailed status information
• ✅ Updated Example: New dark satirical AI prompt
• ✅ API Parameter Fixes: Duration and resolution now work correctly

v0.1.0

• Initial release
• Sora-2 API integration
• Async video generation
• Progress tracking
• Error handling and retry logic
• Example prompts and documentation

---

Development

This repository was generated using Cursor, an AI-powered code editor that accelerates development workflows.

Note: This CLI is built for the official Sora-2 API. Ensure your OpenAI organization is verified before use.