sora2cli

🎬 A powerful command-line interface for OpenAI's Sora 2 video generation API

Generate, remix, and manage AI-powered videos directly from your terminal with an intuitive interactive menu or streamlined CLI commands.

Features

• 🎬 Generate Videos: Create stunning videos from text prompts using Sora 2 or Sora 2 Pro models
• 🔄 Remix Videos: Modify and refine existing videos with targeted adjustments
• ✨ AI Prompt Enhancement: Automatically enhance prompts using GPT-4o-mini for better results
• 📊 Real-time Progress: Monitor generation progress with visual progress bars
• 📥 Download Management: Download videos, thumbnails, and spritesheets
• 📋 Video Library: List and manage your generated videos
• 🎨 Reference Images: Use input images to guide video generation
• ⚡ Two Modes: Interactive menu or direct CLI commands
• 🔒 Privacy-First: Strips metadata from extracted frames

Installation

Prerequisites

• Node.js 18+ (required for ES2022 modules)
• OpenAI API key with Sora access

Setup

1. Clone and install:

git clone https://github.com/robertoamoreno/sora2cli.git
cd sora2cli
npm install

2. Configure environment:

cp .env.example .env
# Edit .env and add your OpenAI API key

3. Build the project:

npm run build

4. (Optional) Install globally:

npm link

Usage

Interactive Mode (Recommended)

Start the interactive menu:

npm start
# or if installed globally:
sora

The interactive mode provides:

• ✨ Generate new video
• 🔄 Remix existing video
• 📋 List videos
• 📥 Download video
• 🗑️ Delete video
• 📊 Check video status

Command-Line Mode

Generate a Video

# Basic generation
sora generate -p "A cat riding a motorcycle through the desert"

# With options
sora generate \
  -p "Wide shot of a teal coupe driving through a desert highway" \
  -m sora-2-pro \
  -s 1920x1080 \
  -d 10 \
  -o ./my-videos

# With reference image
sora generate \
  -p "She turns around and smiles" \
  -r ./reference.jpg \
  -m sora-2-pro

Options:

• -p, --prompt <prompt> - Video prompt (required)
• -m, --model <model> - Model: sora-2 (fast) or sora-2-pro (quality) [default: sora-2]
• -s, --size <size> - Video size [default: 1280x720]
  • Available: 480x480, 768x480, 480x768, 1280x720, 720x1280, 1920x1080, 1080x1920
• -d, --duration <seconds> - Duration: 5, 8, or 10 [default: 8]
• -r, --reference <path> - Path to reference image (JPG, PNG, WebP)
• -o, --output <path> - Output directory [default: ./videos]
• --no-wait - Don't wait for completion

Check Status

sora status video_abc123

Download Video

# Download video
sora download video_abc123

# Download thumbnail
sora download video_abc123 -v thumbnail -o thumb.webp

# Download spritesheet
sora download video_abc123 -v spritesheet -o sprite.jpg

List Videos

# List recent videos
sora list

# List with custom limit
sora list -l 50

Delete Video

sora delete video_abc123

Model Comparison

sora-2

• Speed: Fast generation
• Quality: Good quality
• Use Case: Rapid iteration, social media, prototypes
• Best For: Exploring ideas, quick feedback, concepting

sora-2-pro

• Speed: Slower generation
• Quality: Production-quality output
• Use Case: High-resolution cinematic footage, marketing assets
• Best For: Final deliverables, polished content, precision work

Video Sizes

• Square: 480x480
• Landscape: 768x480, 1280x720, 1920x1080
• Portrait: 480x768, 720x1280, 1080x1920

Effective Prompting

For best results, describe:

1. Shot type: Wide shot, close-up, tracking shot, etc.
2. Subject: What's in the frame
3. Action: What's happening
4. Setting: Location and environment
5. Lighting: Time of day, lighting conditions

Examples

Wide shot of a child flying a red kite in a grassy park, golden hour sunlight, camera slowly pans upward.

Close-up of a steaming coffee cup on a wooden table, morning light through blinds, soft depth of field.

Tracking shot of a teal coupe driving through a desert highway, heat ripples visible, hard sun overhead.

For more advanced techniques, see the Sora 2 Prompting Guide.

Remixing Videos

Remix allows you to modify existing videos with targeted adjustments:

// In interactive mode, select "Remix existing video"
// Or use the API directly:

import { SoraClient } from './build/sora-client.js';

const client = new SoraClient(process.env.OPENAI_API_KEY);

const remix = await client.remix('video_abc123', {
  prompt: 'Change the color palette to teal, sand, and rust'
});

Best Practices:

• Make one clear change per remix
• Keep adjustments focused and specific
• Preserve what already works

Content Restrictions

The API enforces several guardrails:

• Content must be suitable for audiences under 18
• No copyrighted characters or music
• Real people (including public figures) cannot be generated
• Input images with human faces are currently rejected

API Reference

SoraClient

import { SoraClient } from './build/sora-client.js';

const client = new SoraClient(apiKey);

// Create video
const video = await client.create({
  model: 'sora-2',
  prompt: 'A cat on a motorcycle',
  size: '1280x720',
  seconds: '8',
  input_reference: './reference.jpg' // optional
});

// Get status
const status = await client.retrieve(video.id);

// Poll until completion
const completed = await client.poll(video.id, 5000, (video) => {
  console.log(`Progress: ${video.progress}%`);
});

// Create and poll (convenience method)
const video = await client.createAndPoll({
  model: 'sora-2-pro',
  prompt: 'Mountain sunset time-lapse'
});

// Download
await client.downloadContent(video.id, './video.mp4', 'video');
await client.downloadContent(video.id, './thumb.webp', 'thumbnail');
await client.downloadContent(video.id, './sprite.jpg', 'spritesheet');

// List videos
const list = await client.list({ limit: 20 });

// Remix
const remix = await client.remix(video.id, {
  prompt: 'Add rain and fog'
});

// Delete
await client.delete(video.id);

Project Structure

sora2cli/
├── src/
│   ├── index.ts          # CLI entry point & commands
│   ├── cli.ts            # Interactive CLI interface
│   ├── sora-client.ts    # Sora 2 API client
│   └── types.ts          # TypeScript type definitions
├── build/                # Compiled JavaScript output
├── videos/               # Downloaded videos (auto-created)
├── .env                  # API key (create from .env.example)
├── .env.example          # Environment template
├── package.json
├── tsconfig.json
└── README.md

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild)
npm run watch

# Run after building
npm start

Troubleshooting

"OPENAI_API_KEY not found"

Create a .env file with your API key:

OPENAI_API_KEY=sk-...

"Video generation failed"

• Check content restrictions (no copyrighted material, real people, etc.)
• Verify prompt follows guidelines
• Ensure reference image matches target video size

Downloads expire

Download URLs are valid for 24 hours. Download videos promptly or store them in your own system.

Examples

Generate Quick Preview

sora generate \
  -p "Product demo: smartphone rotating on white background" \
  -m sora-2 \
  -d 5 \
  -s 480x480

Generate Production Video

sora generate \
  -p "Cinematic establishing shot of a modern city skyline at dawn, drone camera rising slowly" \
  -m sora-2-pro \
  -d 10 \
  -s 1920x1080

Use Reference Image

sora generate \
  -p "The character walks forward and waves at the camera" \
  -r ./character.png \
  -m sora-2-pro \
  -s 1280x720

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a PR.

Resources

• Sora API Documentation
• Sora 2 Prompting Guide
• OpenAI API Reference