Configuration

from kugelaudio import KugelAudio

# Simple setup
client = KugelAudio(api_key="your_api_key")

# With custom options
client = KugelAudio(
    api_key="your_api_key",                # Required: Your API key
    api_url="https://api.kugelaudio.com",  # Optional: API base URL
    tts_url=None,                          # Optional: separate TTS/WebSocket URL
    timeout=60.0,                          # Optional: Request timeout in seconds
    keepalive_ping_interval=20.0,          # Optional: WS ping interval; None disables
    region=None,                           # Optional: "eu" for the direct EU endpoint
)

Parameter	Type	Default	Description
`api_key`	`str`	required	Your API key. Can be prefixed with `eu-` to select the EU endpoint.
`api_url`	`str \| None`	`https://api.kugelaudio.com`	API base URL. For self-hosted deployments, see Self-Hosted Deployment.
`tts_url`	`str \| None`	same as `api_url`	TTS server URL for WebSocket streaming.
`timeout`	`float`	`60.0`	HTTP request timeout in seconds.
`keepalive_ping_interval`	`float \| None`	`20.0`	Seconds between WebSocket ping frames on the pooled connection to prevent idle timeouts. Set to `None` to disable.
`region`	`str \| None`	`None`	Deployment region. Use `"eu"` for the direct EU endpoint.

Client lifecycle

client = await KugelAudio.create(api_key="your_api_key")
print(client.is_connected())      # True once the pooled async socket is open
await client.aclose()             # Release HTTP + WebSocket resources

KugelAudio is also a context manager, so resources are released automatically:

with KugelAudio(api_key="your_api_key") as client:
    audio = client.tts.generate(text="Hello!", model_id="kugel-3", voice_id=1071)
    audio.save("output.wav")

The async pre-connection methods are also exposed on the TTS resource as client.tts.connect_async() and client.tts.is_connected(). The synchronous connect() method exists, but synchronous generate() and stream() run on their own event-loop thread and do not reuse that socket. Use streaming_session_sync() when a synchronous application needs a persistent streaming connection.

Region Selection

Pin traffic to the direct EU endpoint when needed. See the EU endpoint guide for details.

# Option 1: prefix your API key
client = KugelAudio(api_key="eu-ka_your_api_key")

# Option 2: explicit region parameter
client = KugelAudio(api_key="ka_your_api_key", region="eu")

Next steps

Generate Speech — one-shot generation and parameters
Streaming — streaming sessions and barge-in

Get started

Build a voice agent

Generate audio

Voices

Deploy

SDK Reference

API Reference

Client lifecycle

Region Selection

Next steps

​Client lifecycle

​Region Selection

​Next steps

Client lifecycle

Region Selection

Next steps