Leanvox Python SDK

Official Python SDK for the Leanvox TTS API.

Install

pip install leanvox

Quick Start

from leanvox import Leanvox

client = Leanvox(api_key="lv_live_...")
# or set LEANVOX_API_KEY env var

# Generate speech
result = client.generate(text="Hello from Leanvox!", model="standard")
print(result.audio_url)

# Download audio
result.save("hello.mp3")

Streaming

with client.stream(text="Long narration...", voice="af_heart") as stream:
    with open("output.mp3", "wb") as f:
        for chunk in stream:
            f.write(chunk)

Max (Instruction-Based Voice)

# Describe any voice in natural language
result = client.generate(
    text="Welcome to our podcast!",
    model="max",
    voice_instructions="A warm, confident female narrator with a slight British accent",
)
print(result.generated_voice_id)  # Reuse this ID for consistent voice

Dialogue

result = client.dialogue(
    model="pro",
    lines=[
        {"text": "Welcome to the show!", "voice": "narrator_warm_male", "language": "en"},
        {"text": "Thanks for having me.", "voice": "assistant_pro_female", "language": "en"},
    ],
    gap_ms=500,
)

Async

from leanvox import AsyncLeanvox

async with AsyncLeanvox() as client:
    result = await client.generate(text="Hello async!")

Voice Management

# List voices
voices = client.voices.list(model="pro")

# Clone a voice ($3 to unlock)
voice = client.voices.clone(name="My Voice", audio=open("ref.wav", "rb"))
client.voices.unlock(voice.voice_id)

# Design a voice ($1)
voice = client.voices.design(name="Narrator", prompt="Deep warm male voice")

Error Handling

from leanvox import LeanvoxError, InsufficientBalanceError, RateLimitError

try:
    result = client.generate(text="Hello")
except InsufficientBalanceError as e:
    print(f"Need credits: balance={e.balance_cents}")
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after}")
except LeanvoxError as e:
    print(f"API error: {e.code} - {e.message}")

Auth Priority

1. Constructor param: Leanvox(api_key="...")
2. Environment variable: LEANVOX_API_KEY
3. Config file: ~/.lvox/config.toml

Requirements

• Python 3.9+
• httpx