tarash-gateway 0.1.0

Unified interface for AI video, image, and audio generation models

Tarash Gateway

Unified Python SDK for AI video, image, and audio generation
One interface. Multiple providers. Production-ready.

Documentation  ·  Quick Start  ·  Providers

---

What is Tarash Gateway?

Tarash Gateway abstracts AI media generation across multiple providers behind a single, consistent API. Write one integration and swap providers by changing config — your request code, response handling, and error logic stay identical.

Full documentation at tarash.vertexcover.io

---

Installation

pip install tarash-gateway[fal]

Install only the provider extras you need:

pip install tarash-gateway[openai]       # OpenAI / Azure
pip install tarash-gateway[runway]       # Runway
pip install tarash-gateway[elevenlabs]   # ElevenLabs TTS
pip install tarash-gateway[fal,runway]   # Multiple providers
pip install tarash-gateway[all]          # Everything

Requires Python 3.12+ — see the installation guide for details.

---

Quick Start

Video Generation

from tarash_gateway import VideoGenerationConfig, VideoGenerationRequest, generate_video

config = VideoGenerationConfig(
    model="fal-ai/veo3.1/fast",
    provider="fal",
    api_key="YOUR_FAL_KEY",
)

request = VideoGenerationRequest(
    prompt="Sunset over mountains, cinematic",
    aspect_ratio="16:9",
    duration_seconds=5,
)

response = generate_video(config, request)
print(response.video)  # URL to generated video

Switch providers — your request code stays the same:

config = VideoGenerationConfig(
    model="gen4_turbo", provider="runway", api_key="YOUR_RUNWAY_KEY",
)
response = generate_video(config, request)  # Same request, same response shape

Image Generation

from tarash_gateway import ImageGenerationConfig, ImageGenerationRequest, generate_image

config = ImageGenerationConfig(
    model="fal-ai/flux-2/pro",
    provider="fal",
    api_key="YOUR_FAL_KEY",
)

request = ImageGenerationRequest(
    prompt="A futuristic cityscape at dawn, digital art",
    aspect_ratio="16:9",
)

response = generate_image(config, request)
print(response.image)

Audio — TTS

from tarash_gateway import AudioGenerationConfig, TTSRequest, generate_tts

config = AudioGenerationConfig(
    model="eleven_multilingual_v2",
    provider="elevenlabs",
    api_key="YOUR_ELEVENLABS_KEY",
)

request = TTSRequest(
    text="Hello from Tarash!",
    voice_id="your-voice-id",
    output_format="mp3_44100_128",
)

response = generate_tts(config, request)
# response.audio — base64-encoded audio
# response.content_type — e.g. "audio/mpeg"

Async & Provider Fallback

Every function has an async variant:

from tarash_gateway import generate_video_async

response = await generate_video_async(config, request)

Set up automatic fallback across providers:

config = VideoGenerationConfig(
    model="fal-ai/veo3.1/fast",
    provider="fal",
    api_key="YOUR_FAL_KEY",
    fallback_configs=[
        VideoGenerationConfig(
            model="gen4_turbo",
            provider="runway",
            api_key="YOUR_RUNWAY_KEY",
        ),
    ],
)

# Falls back to Runway automatically if Fal fails
response = generate_video(config, request)

See the guides for more examples.

---

Providers

Provider	Video	Image	Audio
Fal.ai	✓	✓	✓
OpenAI	✓	✓	—
Google	✓	✓	—
Runway	✓	—	—
Replicate	✓	—	—
XAI	✓	—	—
Stability AI	—	✓	—
ElevenLabs	—	—	✓
Cartesia	—	—	✓
Sarvam	—	—	✓
Hume	—	—	✓

Full model list and provider details at tarash.vertexcover.io/providers

---

Features

Feature	Description
Sync + Async	Every function has generate_* and generate_*_async variants
Provider Fallback	Automatic failover across a prioritized provider chain
Progress Callbacks	Real-time updates during long-running generation
Type-Safe	Pydantic v2 models with full IDE autocomplete
Rich Errors	Every exception includes provider, model, request_id, and raw response
Mock Provider	Deterministic fake responses for testing without API calls
Structured Logging	Automatic credential redaction and request tracing

---

Architecture

tarash_gateway/
├── api.py                  # Public API
├── models.py               # Request/response models
├── exceptions.py           # Exception hierarchy
├── orchestrator.py         # Fallback and retry orchestration
├── mock.py                 # Mock provider for testing
├── logging.py              # Structured logging
└── providers/              # Provider implementations + field mapper registry

Key design principles:

• All providers implement the same ProviderHandler protocol
• Declarative parameter translation via a field mapper registry
• Immutable, thread-safe configuration with frozen Pydantic models
• Every operation available in both sync and async modes

---

Development

Requirements: Python 3.12+, uv

git clone https://github.com/vertexcover-io/tarash.git
cd tarash
uv sync

# Unit tests (no API keys needed)
uv run pytest packages/tarash-gateway/tests/unit/

# End-to-end tests (requires API keys)
uv run pytest packages/tarash-gateway/tests/e2e/ --e2e

---

License

MIT — see LICENSE for details.