leanvox 0.4.0

Official Python SDK for the Leanvox TTS API

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