> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the KugelAudio Python SDK and generate your first audio

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

## Installation

```bash theme={null}
pip install kugelaudio
```

Or with uv (recommended):

```bash theme={null}
uv add kugelaudio
```

## Quick Start

```python theme={null}
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](/latency).

### Async Applications (Recommended)

```python theme={null}
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:

```python theme={null}
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)
```

<Tip>
  Without pre-connecting, the first TTS request includes WebSocket connection setup.
  Subsequent requests reuse the connection. See [Latency](/latency) for typical numbers.
  Pre-connecting moves this overhead to application startup.
</Tip>

## Complete Example

```python theme={null}
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

* [Configuration](/sdks/python/configuration) — client options, lifecycle, region selection
* [Generate Speech](/sdks/python/generate) — one-shot generation, parameters, word timestamps
* [Streaming](/sdks/python/streaming) — streaming sessions, barge-in, multi-context sessions
* [Text Normalization](/sdks/python/normalization) — languages and spell tags
* [Voices](/sdks/python/voices) — list, create, and manage voices
* [Dictionaries](/sdks/python/dictionaries) — per-project pronunciation lists
* [Types & Errors](/sdks/python/types) — exceptions, data models, enums