Sora API Request Toolkit

Utilities and helper modules for working with OpenAI's Sora video generation endpoints. The toolkit ships with three primary CLI scripts and a shared library that streamline common workflows such as submitting prompts, downloading assets, and keeping local artefacts organised.

Requirements

Requirement	Purpose
Python 3.9+	Required to run the CLI utilities.
OPENAI_API_KEY	Grants access to the OpenAI Sora endpoints and GPT-based fallbacks.
Ollama with gemma3:latest	Provides fast local subject detection. This is the only local model the scripts will attempt to use.
ffmpeg / ffprobe	Optional but recommended for extracting still frames during subject detection and for normalising filenames.

The scripts automatically detect whether Ollama is available. If gemma3:latest is missing, the utilities fall back to OpenAI's lightweight gpt-5-nano model for subject extraction.

Setup

1. Clone the repository and create a virtual environment (recommended):

   git clone https://github.com/your-org/sora2-api-requests.git
   cd sora2-api-requests
   python3 -m venv .venv
   source .venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Configure credentials and optional services:

   • Export your OpenAI API key: export OPENAI_API_KEY="sk-...".

   • Install and start Ollama, then pull the supported model:

     ollama pull gemma3:latest

     The scripts verify Ollama availability before each subject-detection request and gracefully fall back to OpenAI if the model cannot be loaded.

4. (Optional) Adjust the Ollama host with OLLAMA_API_URL if it does not run on http://localhost:11434.

Usage

Generate a new Sora video

python3 generate_sora_video.py "A calm koi pond at dusk" --wait

Highlights:

• --wait polls the job until the requested variant is ready, displaying progress updates.
• --variant selects the downloadable asset (video, thumbnail, or spritesheet).
• --input-reference allows you to upload an image or video to guide the generation.
• --config loads defaults from sora_config.json (see below). Running --config without a value launches the interactive wizard.

List and manage existing jobs

python3 list_sora_videos.py --limit 5 --download-all --wait

• Use --delete-id to remove a remote job, or --video-id to download a specific entry directly.
• --download-all saves every listed job that has not already been archived locally.
• Automatic subject detection enriches metadata; when Ollama is unavailable the script transparently switches to GPT-based extraction.

Organise downloaded assets

python3 organize_sora_outputs.py --dry-run
python3 organize_sora_outputs.py  # apply the changes

• Reads each metadata file in output/, infers or re-detects the subject, and renames both the video and JSON to a canonical form (subject-videoid.ext).
• With --skip-detection, the script avoids LLM calls and uses existing metadata only.

Configuration Wizard (--config)

Running any script with --config launches a guided setup that helps you capture repeatable defaults:

1. Choose a starting profile – e.g. Quick repeatability (4 s clip, 720×1280) or High-quality review (8 s clip, HD quality). Profiles pre-populate common parameters but you can tweak every field afterwards.
2. Adjust individual values – duration, resolution, variant, polling cadence, output directory, etc. Press Enter to keep the suggested value.
3. Opt-in for repeat runs – confirm whether the captured defaults should be reused automatically when the script runs again.
4. Review and save – the wizard shows a summary before writing sora_config.json (or a custom path if specified). The file includes metadata that records the selected profile for future edits.

Defaults are loaded automatically from sora_config.json or .sora_config.json in the working directory. Provide a path to --config to use or create a different profile.

Subject detection behaviour

• Primary backend: Ollama running the gemma3:latest model. The code verifies model availability via the HTTP API and CLI before sending a request.
• Fallback: If Ollama is not reachable or the model is missing, detection seamlessly falls back to OpenAI's gpt-5-nano without interrupting the workflow.
• Video analysis: When organising outputs, a single frame is sampled (using ffmpeg) and analysed through the same Ollama check to enrich metadata with a subject slug.

Project structure

generate_sora_video.py   # Submit prompts and download results
list_sora_videos.py       # Browse, download, and clean up video jobs
organize_sora_outputs.py  # Normalise local artefacts
sora_tools/               # Shared helpers used by the scripts
sora_cli/                 # Legacy helpers retained for backwards compatibility

Feel free to adapt the utilities for automation pipelines. Each script is self-contained and designed to run both interactively and inside batch jobs.