Skip to main content
The official Python SDK for KugelAudio provides a simple, Pythonic interface for text-to-speech generation with both synchronous and asynchronous support.

​
Installation

pip install kugelaudio
Or with uv (recommended): 
uv add kugelaudio

​
Quick Start

from kugelaudio import KugelAudio

# Initialize the client
client = KugelAudio(api_key="your_api_key")

# Generate speech
audio = client.tts.generate(
    text="Hello, world!",
    model_id="kugel-3",
)

# Save to file
audio.save("output.wav")

​
Pre-connecting for Low Latency

For latency-sensitive applications, pre-establish the WebSocket connection at startup to keep the handshake out of your first TTS request — see Latency. 
import asyncio
from kugelaudio import KugelAudio

async def main():
    # Create a pre-connected client (handshake happens here)
    client = await KugelAudio.create(api_key="your_api_key")
    
    # First request is now fast — no handshake on the hot path
    async for chunk in client.tts.stream_async("Hello, world!"):
        if hasattr(chunk, 'audio'):
            play_audio(chunk.audio)
    
    await client.aclose()

asyncio.run(main())

​
Sync Applications

For synchronous code, manually call connect() at startup: 
from kugelaudio import KugelAudio

# Initialize client
client = KugelAudio(api_key="your_api_key")

# Pre-connect at startup (handshake happens here)
client.connect()

# Check connection status
print(f"Connected: {client.is_connected()}")

# First request is now fast
for chunk in client.tts.stream("Hello, world!"):
    if hasattr(chunk, 'audio'):
        play_audio(chunk.audio)
Without pre-connecting, the first TTS request includes WebSocket connection setup. Subsequent requests reuse the connection. See Latency for typical numbers. Pre-connecting moves this overhead to application startup.

​
Complete Example

from kugelaudio import KugelAudio

# Initialize client
client = KugelAudio(api_key="your_api_key")

# List available models
print("Available Models:")
for model in client.models.list():
    print(f"  - {model.id}: {model.name}")

# List available voices
print("\nAvailable Voices:")
result = client.voices.list(limit=5)
for voice in result.voices:
    print(f"  - {voice.id}: {voice.name}")

# Generate audio
print("\nGenerating audio...")
audio = client.tts.generate(
    text="Welcome to KugelAudio. This is an example of high-quality text-to-speech synthesis.",
    model_id="kugel-3",
)

print(f"Generated {audio.duration_seconds:.2f}s of audio in {audio.generation_ms:.0f}ms")
print(f"Real-time factor: {audio.rtf:.2f}x")

# Save to file
audio.save("example.wav")
print("Saved to example.wav")

# Close client
client.close()

​
Next steps