Skip to main content
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
)
ParameterTypeDefaultDescription
api_keystrrequiredYour API key. Can be prefixed with eu- to select the EU endpoint.
api_urlstr | Nonehttps://api.kugelaudio.comAPI base URL. For self-hosted deployments, see Self-Hosted Deployment.
tts_urlstr | Nonesame as api_urlTTS server URL for WebSocket streaming.
timeoutfloat60.0HTTP request timeout in seconds.
keepalive_ping_intervalfloat | None20.0Seconds between WebSocket ping frames on the pooled connection to prevent idle timeouts. Set to None to disable.
regionstr | NoneNoneDeployment region. Use "eu" for the direct EU endpoint.

​
Client lifecycle

client = KugelAudio(api_key="your_api_key")

client.connect()                  # Pre-open the WebSocket (sync)
print(client.is_connected())      # True once the socket is open
client.close()                    # Release HTTP + WebSocket resources

# Async equivalents
await client.connect_async()
await client.aclose()
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")
    audio.save("output.wav")
The same pre-connection methods are exposed on the TTS resource directly — client.tts.connect(), client.tts.connect_async(), and client.tts.is_connected() — if you only want to manage the streaming socket.

​
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