sanzaru

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.

Related MCP server: mcp-media-engine

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)

From Source

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

Claude Desktop

Add to your claude_desktop_config.json:

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

Or from source:

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

Codex MCP

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

Manual Setup

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