Sanzaru

PyPI version Python versions License CI PyPI downloads

A stateless, lightweight MCP server and agent CLI that wraps OpenAI's Sora Video API, Whisper, GPT-4o Audio, and TTS APIs via the OpenAI Python SDK.

Features

Video Generation (Sora)

• Create videos with sora-2 or sora-2-pro models
• Use reference images to guide generation
• Remix and refine existing videos
• Download variants (video, thumbnail, spritesheet)

Image Generation

• Generate images with gpt-image-2 (recommended), gpt-image-1.5, or GPT-5
• Edit and compose images with up to 16 inputs
• Iterative refinement via Responses API
• Automatic resizing for Sora compatibility

Audio Processing

• Transcription: Whisper and GPT-4o models
• Audio Chat: Interactive analysis with GPT-4o
• Text-to-Speech: Multi-voice TTS generation
• Processing: Format conversion, compression, file management

Podcast Generation

• Multi-voice podcasts with up to 4 speakers and 10 TTS voices
• Parallel segment generation with configurable pacing
• MP3/WAV output with loudness normalization

Agent CLI

• Every capability as a shell command: sanzaru video create, sanzaru image generate, ...
• One-shot async workflows: create ... -o out.mp4 submits, polls, downloads in one command
• JSON envelopes on stdout, progress on stderr, deterministic exit codes, resumable waits
• Concurrent fan-out (multi-prompt image batches, multi-job wait) and arbitrary -o output paths
• See docs/cli.md — bare sanzaru still runs the MCP server (nothing breaks)

Note: Content guardrails are enforced by OpenAI. This server does not run local moderation.

Requirements

• Python 3.10+
• OPENAI_API_KEY environment variable

Media storage (choose one):

# Recommended: unified path (auto-creates videos/, images/, audio/ subdirs)
SANZARU_MEDIA_PATH="/path/to/media"

# Or individual paths (legacy, still supported)
VIDEO_PATH="/path/to/videos"
IMAGE_PATH="/path/to/images"
AUDIO_PATH="/path/to/audio"

Features are auto-detected based on configured paths. Set only what you need.

Quick Start

1. Clone the repository:

   git clone https://github.com/TJC-LP/sanzaru.git
   cd sanzaru
   

2. Run the setup script:

   ./setup.sh
   

   The script will:

   • Prompt for your OpenAI API key
   • Create directories and .env configuration
   • Install dependencies with uv sync --all-extras --dev

3. Start using:

   claude
   

That's it! Claude Code will automatically connect and you can start generating videos, images, and processing audio.

Or skip MCP entirely — the agent CLI

uv tool install sanzaru && export OPENAI_API_KEY=sk-...

# One command: submit Sora job → poll → download → print the file path
sanzaru video create "a tabby cat stretches on a windowsill" --seconds 4 -o ./cat.mp4 | jq -r .result.file.path

# Synchronous image generation (gpt-image-2), batch fan-out, JSONL output
sanzaru image generate "app icon" "hero banner" --quality high -o ./art/

sanzaru capabilities   # machine-readable: what's enabled here

JSON envelopes on stdout, progress on stderr, exit 4 = still-running-and-resumable. Full reference: docs/cli.md.

Installation

Claude Code Plugin (Recommended)

Install as a plugin — auto-configures the MCP server + includes prompting guidance:

/plugin marketplace add TJC-LP/sanzaru

Requires OPENAI_API_KEY and SANZARU_MEDIA_PATH environment variables to be set.

Quick Install

# All features
uv add "sanzaru[all]"

# Specific features
uv add "sanzaru[audio]"  # With audio support
uv add sanzaru           # Base (video + image only)

git clone https://github.com/TJC-LP/sanzaru.git
cd sanzaru
uv sync --all-extras

{
  "mcpServers": {
    "sanzaru": {
      "command": "uvx",
      "args": ["sanzaru[all]"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "SANZARU_MEDIA_PATH": "/absolute/path/to/media"
      }
    }
  }
}

{
  "mcpServers": {
    "sanzaru": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sanzaru", "sanzaru"]
    }
  }
}

# Using uvx (from PyPI)
codex mcp add sanzaru \
  --env OPENAI_API_KEY="sk-..." \
  --env SANZARU_MEDIA_PATH="$HOME/sanzaru-media" \
  -- uvx "sanzaru[all]"

uv venv
uv sync

# Set required environment variables
export OPENAI_API_KEY=sk-...
export SANZARU_MEDIA_PATH=~/sanzaru-media

# Run server (stdio for MCP clients)
uv run sanzaru

# Or HTTP mode (for remote access)
uv run sanzaru --transport http --port 8000

Available Tools

Full API documentation: See docs/api-reference.md

Basic Workflows

Generate a Video

# Create video from text
video = create_video(
    prompt="A serene mountain landscape at sunrise",
    model="sora-2",
    seconds="8",
    size="1280x720"
)

# Poll for completion
status = get_video_status(video.id)

# Download when ready
download_video(video.id, filename="mountain_sunrise.mp4")

Generate with Reference Image

# 1. Generate reference image (gpt-image-2, synchronous)
generate_image(
    prompt="futuristic pilot in mech cockpit",
    size="1536x1024",
    filename="pilot.png"
)

# 2. Prepare for video (resize to Sora dimensions)
prepare_reference_image("pilot.png", "1280x720", resize_mode="crop")

# 3. Animate
video = create_video(
    prompt="The pilot looks up and smiles",
    size="1280x720",
    input_reference_filename="pilot_1280x720.png"
)

Audio Transcription

# List available audio files
files = list_audio_files(format="mp3")

# Transcribe
result = transcribe_audio("interview.mp3")

# Or analyze with GPT-4o
analysis = chat_with_audio(
    "meeting.mp3",
    user_prompt="Summarize key decisions and action items"
)

Generate a Podcast

generate_podcast(script={
    "title": "AI Weekly",
    "speakers": [
        {"id": "host", "name": "Alex", "voice": "nova"},
        {"id": "guest", "name": "Sam", "voice": "echo"}
    ],
    "segments": [
        {"speaker": "host", "text": "Welcome to AI Weekly!"},
        {"speaker": "guest", "text": "Thanks for having me."}
    ]
})

Documentation

• API Reference - Complete tool documentation with parameters and examples
• Reference Images Guide - Working with reference images and resizing
• Image Generation Guide - Generating and editing reference images
• Sora Prompting Guide - Crafting effective video prompts
• Audio Features - Audio transcription, chat, and TTS
• Performance & Architecture - Technical details and benchmarks

Transport Modes

Storage Backends

The Databricks backend supports per-user storage isolation via the user_context module, enabling multi-tenant deployments where each user's media is stored under their own volume prefix.

See CLAUDE.md for full configuration details.

Performance

Fully asynchronous architecture with proven scalability:

• ✅ 32+ concurrent operations verified
• ✅ 8-10x speedup for parallel tasks
• ✅ Non-blocking I/O with aiofiles + anyio
• ✅ Python 3.14 free-threading ready

See docs/async-optimizations.md for technical details.

License

MIT