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
| Selection | Endpoint | Behavior |
|---|---|---|
| Default | api.kugelaudio.com | Canonical geo-routed API |
eu | api.eu.kugelaudio.com | Direct EU endpoint |
API URL https://api.us.kugelaudio.com | api.us.kugelaudio.com | Direct US endpoint; pin US traffic by setting the API URL |
us / global | api.kugelaudio.com | Supported 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:
# .env
KUGELAUDIO_API_KEY=eu-YOUR_API_KEYNo 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:
from kugelaudio import KugelAudio
client = KugelAudio(api_key="YOUR_API_KEY", region="eu")With the async client:
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())import { KugelAudio } from 'kugelaudio';
const client = new KugelAudio({
apiKey: 'YOUR_API_KEY',
region: 'eu',
});import com.kugelaudio.sdk.*;
KugelAudio client = new KugelAudio(
KugelAudioOptions.builder("YOUR_API_KEY")
.region(Region.EU)
.build()
);Call the EU host directly, with the key without the eu- prefix:
curl -X POST https://api.eu.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hello from KugelAudio!", "model_id": "kugel-3.5", "voice_id": 1071}'Priority
When multiple EU endpoint hints are present, the SDK resolves them in this order:
- Explicit API URL:
api_urlin Python,apiUrlin JavaScript, orapiUrlin Java region: explicit EU region parameter- API key prefix:
eu- - 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:
wss://api.eu.kugelaudio.com/ws/tts?api_key=YOUR_API_KEYFAQ
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:
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.