TTS.ai Python SDK

Installation

pip install ttsai

pip install ttsai[async]

Quick Start

from tts_ai import TTSClient
client = TTSClient(api_key="sk-tts-...")
# Generate speech (returns audio bytes)
audio = client.generate("Hello world!", model="kokoro", voice="af_bella")
with open("output.wav", "wb") as f:
 f.write(audio)

export TTS_API_KEY=sk-tts-...

client = TTSClient() # Uses TTS_API_KEY from environment

API Key

Usage

Text-to-Speech

from tts_ai import TTSClient
client = TTSClient(api_key="sk-tts-...")
# Basic generation
audio = client.generate("Hello world!")
with open("output.wav", "wb") as f:
 f.write(audio)
# With options
audio = client.generate(
 "Welcome to TTS.ai!",
 model="chatterbox", # Any supported model
 voice="af_bella",
 output_format="mp3",
 speed=1.2,
)

OpenAI Drop-In Replacement

audio = client.generate(
 "Hello from TTS.ai!",
 model="tts-1", # Maps to kokoro
 voice="alloy", # Maps to af_bella
 output_format="mp3",
)

Async TTS (Non-Blocking)

# Start generation (returns immediately)
result = client.generate_async("Long text here...", model="tortoise")
print(f"Job UUID: {result.uuid}")
# Poll for result
audio = client.poll_result(result.uuid, timeout=300)
with open("output.wav", "wb") as f:
 f.write(audio)

Speech-to-Text

# Transcribe from file path
result = client.transcribe("recording.wav")
print(result.text)
print(result.language)
# Transcribe from bytes
with open("recording.wav", "rb") as f:
 audio_bytes = f.read()
result = client.transcribe(audio_bytes, model="faster-whisper")
print(result.text)

Voice Cloning

result = client.clone_voice(
 name="My Voice",
 file="reference.wav",
 model="chatterbox", # or cosyvoice2, openvoice, spark, etc.
 text="Hello in my cloned voice!",
)
print(f"Clone job: {result.uuid}")

List Voices and Models

# List all voices
voices = client.list_voices()
for v in voices:
 print(f"{v.voice_id}: {v.name} ({v.language}, {v.gender})")
# Filter by model
kokoro_voices = client.list_voices(model="kokoro")
# List available models
models = client.list_models()
for m in models:
 print(f"{m.name} ({m.tier}): {m.credits_per_1k} credits per 1k chars")

Batch Generation

items = [
 {"text": "First sentence.", "model": "kokoro", "voice": "af_bella"},
 {"text": "Second sentence.", "model": "kokoro", "voice": "af_heart"},
 {"text": "Third sentence.", "model": "chatterbox", "voice": "af_bella"},
]
# Start batch
result = client.batch_generate(items)
print(f"Batch {result.batch_id}: {result.total} items")
# Check progress
status = client.batch_result(result.batch_id)
print(f"Completed: {status.completed}/{status.total}")
# Or generate and wait for completion
result = client.batch_generate_and_wait(items, timeout=300)

result = client.batch_generate(
 items,
 webhook_url="https://yoursite.com/webhook/tts-complete",
)

Context Manager

with TTSClient(api_key="sk-tts-...") as client:
 audio = client.generate("Hello!")

Async Client

import asyncio
from tts_ai import AsyncTTSClient
async def main():
 async with AsyncTTSClient(api_key="sk-tts-...") as client:
 # All methods are async
 audio = await client.generate("Hello world!")
 with open("output.wav", "wb") as f:
 f.write(audio)
 # Parallel generation
 tasks = [
 client.generate("First sentence.", voice="af_bella"),
 client.generate("Second sentence.", voice="af_heart"),
 ]
 results = await asyncio.gather(*tasks)
asyncio.run(main())

Error Handling

from tts_ai import TTSClient
from tts_ai.exceptions import (
 AuthenticationError,
 InsufficientCreditsError,
 RateLimitError,
 ModelNotFoundError,
 TimeoutError,
 TTSError,
)
client = TTSClient(api_key="sk-tts-...")
try:
 audio = client.generate("Hello!", model="kokoro")
except AuthenticationError:
 print("Invalid API key")
except InsufficientCreditsError as e:
 print(f"Not enough credits (have {e.credits_remaining}, need {e.credits_needed})")
except RateLimitError:
 print("Rate limit exceeded, try again later")
except ModelNotFoundError:
 print("Model not found")
except TimeoutError:
 print("Request timed out")
except TTSError as e:
 print(f"API error ({e.status_code}): {e.message}")

Available Models

Configuration

License