DEV Community

Cover image for Sora 2 / Sora 2 Pro Python CLI
Ibrohim Abdivokhidov
Ibrohim Abdivokhidov

Posted on

Sora 2 / Sora 2 Pro Python CLI

#ai #webdev #programming #javascript

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-2 and sora-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_KEY env var; optional .env support

*Note: Reference image should be specific size.

Requirements

  • Python 3.9+
  • Dependencies:
    • Standard library only for HTTP
    • Optional: python-dotenv if you want .env loading

Install optional dependency:

pip install python-dotenv
Enter fullscreen mode Exit fullscreen mode

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-..."
Enter fullscreen mode Exit fullscreen mode

Or create a .env file:

echo 'OPENAI_API_KEY=sk-...' > .env
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Cat Backflip
Crosswalk and Car

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
Enter fullscreen mode Exit fullscreen mode

Poll until completion and download when ready:

python main.py poll vid_123 --download -o output.mp4
Enter fullscreen mode Exit fullscreen mode

Download content directly:

python main.py download vid_123 -o output.mp4
Enter fullscreen mode Exit fullscreen mode

List, retrieve, and delete:

python main.py list --limit 10
python main.py retrieve vid_123
python main.py delete vid_123
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Arguments and Validation

  • Models: sora-2, sora-2-pro
  • Durations: 4, 8, 12 seconds
  • 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 ...
Enter fullscreen mode Exit fullscreen mode

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_KEY is 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 poll with --download or set up webhooks in your OpenAI account (when available) to avoid polling.

Top comments (0)