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", "us", or "global"
)

Parameter	Type	Default	Description
`api_key`	`str`	required	Your API key. A `eu-`, `us-`, or `global-` prefix selects the region; the SDK strips it before authenticating.
`api_url`	`str \| None`	`https://api.kugelaudio.com`	API base URL. For self-hosted deployments, see On-Premise 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`	`"eu"`, `"us"`, or `"global"`. `"eu"` selects the direct EU endpoint; the other values use the default geo-routed endpoint.

When several are set, api_url wins over region, and region wins over an API-key prefix.

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.create() accepts the same options as the constructor plus model (default "kugel-3"), the model the pooled socket is opened for. 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. stream_async() reuses the pooled socket by default. Pass reuse_connection=False to open a fresh connection for that call.

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")

The key prefix is an SDK convenience: the SDK removes it and routes to the EU host. Raw HTTP or WebSocket clients call https://api.eu.kugelaudio.com with the key without the prefix.

Diagnostics

The SDK reports its own connection and streaming failures back to KugelAudio so we can see problems that never reach our servers. It never sends your text, audio or credentials. See SDK Diagnostics for the full field list and the opt-out.

Next steps

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

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Client lifecycle

Region Selection

Diagnostics

Next steps

​Client lifecycle

​Region Selection

​Diagnostics

​Next steps

Client lifecycle

Region Selection

Diagnostics

Next steps