Skip to content
KugelAudioDocs

Regions

Choose between the canonical geo-routed KugelAudio endpoint and the direct EU endpoint for data residency, and set the region by API key prefix or in code.

On this page

By default, SDKs use the canonical geo-routed endpoint. Select the direct EU endpoint only when you need to pin traffic to Europe.

Endpoint Options

SelectionEndpointBehavior
Defaultapi.kugelaudio.comCanonical geo-routed API
euapi.eu.kugelaudio.comDirect EU endpoint
API URL https://api.us.kugelaudio.comapi.us.kugelaudio.comDirect US endpoint; pin US traffic by setting the API URL
us / globalapi.kugelaudio.comSupported compatibility hints: region="us" routes to the canonical endpoint, not the US host

How to Set Your Region

The SDKs select the direct EU endpoint from an API-key prefix or an explicit region. You can also bypass region resolution by supplying an API URL directly. Without an SDK, call the EU host yourself.

Option 1: Prefix Your API Key (SDKs only)

Prepend eu- to your API key. The SDK strips the prefix before sending the key and routes the request to the EU endpoint:

Bash
# .env
KUGELAUDIO_API_KEY=eu-YOUR_API_KEY

No code changes needed. The prefix is an SDK feature: the API itself does not recognize it, so a raw HTTP or WebSocket request with a prefixed key fails with 401 Invalid API key.

Option 2: Set the Region in Code

All SDKs accept an explicit EU region parameter:

Python
from kugelaudio import KugelAudio

client = KugelAudio(api_key="YOUR_API_KEY", region="eu")

With the async client:

Python
import asyncio
from kugelaudio import KugelAudio

async def main():
    client = await KugelAudio.create(api_key="YOUR_API_KEY", region="eu")
    await client.aclose()

asyncio.run(main())

Priority

When multiple EU endpoint hints are present, the SDK resolves them in this order:

  1. Explicit API URL: api_url in Python, apiUrl in JavaScript, or apiUrl in Java
  2. region: explicit EU region parameter
  3. API key prefix: eu-
  4. Default: canonical geo-routed API (api.kugelaudio.com)

WebSocket Connections

EU endpoint selection applies to both REST and WebSocket endpoints. The SDK automatically uses the correct host for WebSocket connections. Raw WebSocket clients connect to the EU host with the unprefixed key:

Text
wss://api.eu.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY

FAQ

Do I need to change anything if I use the default endpoint?

If you want automatic geo-routing, no. If you need to pin traffic to Europe, set region="eu" or the eu- key prefix in an SDK, or call api.eu.kugelaudio.com directly.

Are voices and models the same across regions?

Yes for models: api.kugelaudio.com and api.eu.kugelaudio.com both serve kugel-3 and kugel-3.5, with the same default model and the same legacy and ElevenLabs ID mapping. An on-premise deployment serves only the models it was installed with. Query /v1/models and /v1/voices on the endpoint you plan to use to confirm its catalog and your custom-voice availability:

Bash
curl https://api.eu.kugelaudio.com/v1/models \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"
Can I switch regions without getting a new API key?

Yes. Your API key works with the default and EU endpoints. In an SDK, add or remove the eu- prefix or the region="eu" parameter; without an SDK, change the host. No need to regenerate keys.

Next steps