Skip to content
KugelAudioDocs

ElevenLabs API Compatibility

Use ElevenLabs SDKs and integrations with the ElevenLabs-compatible KugelAudio API: swap the base URL, voice ID and output format, and see the endpoints.

On this page

KugelAudio exposes an ElevenLabs-compatible subset of the HTTP and WebSocket API. Point a supported ElevenLabs SDK or integration at the KugelAudio base URL, then update its voice ID and output format as described below.

RegionBase URL
Default (geo-routed)https://api.kugelaudio.com/11labs
EU (pins traffic to Europe)https://api.eu.kugelaudio.com/11labs

The examples below use the default host; swap in the EU base URL to keep requests in Europe, as described in Regions. The WebSocket endpoint follows the same host (wss://api.eu.kugelaudio.com/11labs/...).

Quick Start

Python SDK

Python
from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="your-kugelaudio-api-key",
    base_url="https://api.kugelaudio.com/11labs",
)

audio = client.text_to_speech.convert(
    voice_id="480",  # use client.voices.get_all() to list available voices
    text="Hello from KugelAudio!",
    model_id="kugel-3.5",
    output_format="pcm_24000",
)

with open("output.pcm", "wb") as f:
    for chunk in audio:
        f.write(chunk)

Node.js SDK

TypeScript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({
  apiKey: "your-kugelaudio-api-key",
  baseUrl: "https://api.kugelaudio.com/11labs",
});

const stream = await client.textToSpeech.stream("480", {
  text: "Hello from KugelAudio!",
  modelId: "kugel-3.5",
  outputFormat: "pcm_24000",
});

Migrating from ElevenLabs

The only changes needed:

  1. Replace base_url: point to your KugelAudio server
  2. Update voice_id: use KugelAudio voice IDs (not ElevenLabs IDs)
  3. Update output_format: use a PCM format for lowest overhead, or MP3 for integrations that require ElevenLabs' default response shape (see Output Formats)
Python
# Before
client = ElevenLabs(api_key="your-elevenlabs-key")

# After
client = ElevenLabs(
    api_key="your-kugelaudio-key",
    base_url="https://api.kugelaudio.com/11labs",
)

List your available voices to get the right IDs:

Python
voices = client.voices.get_all()
for v in voices.voices:
    print(f"{v.voice_id}: {v.name}")

Migrating a streaming integration

On KugelAudio's /ws/tts/stream, each flush ends the turn and the next text pays a fresh model prefill, so do not translate ElevenLabs flushes one-to-one. See Chunking & per-segment latency for why.

The right translation:

ElevenLabs patternKugelAudio equivalent
send(text, flush=True) after every chunksend(text) with no flush; let the server's text buffer chunk.
try_trigger_generation=TrueDefault behavior. The server starts generation at sentence boundaries automatically.
auto_mode=trueAccepted for compatibility; native KugelAudio streaming uses its sentence-aware server buffer.
One context per turnOne turn per flush on a long-lived StreamingSession. See Turn lifecycle.

Output Formats

KugelAudio generates audio natively at 24 kHz PCM16. Lower sample rates use server-side resampling. MP3 output is encoded server-side for ElevenLabs-compatible tools that expect audio/mpeg.

FormatStatusNotes
pcm_24000✅ RecommendedNative rate, zero conversion cost
pcm_22050✅ Supported
pcm_16000✅ SupportedCommon for telephony
pcm_8000✅ Supported
pcm_44100✅ SupportedHigher-rate PCM for ElevenLabs compatibility
mp3_44100, mp3_44100_128✅ Supported128 kbps; mp3_44100_128 is also selected when Accept: audio/mpeg is sent without output_format
mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_192✅ SupportedExplicit 44.1 kHz bitrates
mp3_22050, mp3_22050_128✅ Supported128 kbps at 22.05 kHz
mp3_22050_32, mp3_22050_64, mp3_22050_96, mp3_22050_192✅ SupportedExplicit 22.05 kHz bitrates
ulaw_8000✅ SupportedG.711 µ-law at 8 kHz; audio/basic, audio.ulaw
alaw_8000✅ SupportedG.711 a-law at 8 kHz; audio/basic, audio.alaw

Open WebUI

Open WebUI's ElevenLabs TTS path sends Accept: audio/mpeg and saves the response as an .mp3 file. KugelAudio honors that header on /11labs/v1/text-to-speech/{voice_id} and returns audio/mpeg MP3 bytes when no explicit output_format query parameter is present.

Supported Endpoints

Text-to-Speech

EndpointMethodStatus
/v1/text-to-speech/{voice_id}POST✅ Supported
/v1/text-to-speech/{voice_id}/streamPOST✅ Supported
/v1/text-to-speech/{voice_id}/stream-inputWebSocket✅ Supported

About stream-input: Feed text tokens as they arrive from an LLM: synthesis starts as soon as a sentence boundary is detected, minimizing time-to-first-audio. The server sends ElevenLabs-format audio frames ({"audio": "<base64>", "isFinal": false}), then {"audio": "", "isFinal": true}, then closes the WebSocket with code 1000. That normal close is required for the official ElevenLabs Python SDK (convert_realtime), which keeps reading until the server closes (it does not stop on isFinal alone).

Python
import asyncio, base64, json
import websockets

async def stream_tts():
    url = "wss://api.kugelaudio.com/11labs/v1/text-to-speech/480/stream-input?model_id=eleven_turbo_v2&output_format=pcm_24000"
    # websockets >= 14 takes additional_headers (extra_headers was the legacy name)
    async with websockets.connect(url, additional_headers={"xi-api-key": "your-api-key"}) as ws:
        # Send text tokens one by one (e.g. from an LLM stream)
        for token in ["Hello, ", "this is ", "streamed ", "speech."]:
            await ws.send(json.dumps({"text": token}))

        # Signal end of stream
        await ws.send(json.dumps({"text": ""}))

        # Receive audio frames
        with open("output.pcm", "wb") as f:
            async for msg in ws:
                frame = json.loads(msg)
                if frame.get("isFinal"):
                    break
                if audio := frame.get("audio"):
                    f.write(base64.b64decode(audio))

asyncio.run(stream_tts())

Voices

EndpointMethodStatus
/v1/voicesGET✅ Supported
/v1/voices/{voice_id}GET✅ Supported
/v1/voices/addPOST❌ Not supported
/v1/voices/{voice_id}/editPOST❌ Not supported

Other

EndpointMethodStatus
/v1/modelsGET✅ Supported
/v1/userGET❌ Not supported
/v1/user/subscriptionGET❌ Not supported
/v1/historyGET❌ Not supported

Available Models

Model ID (ElevenLabs alias)KugelAudio model
eleven_turbo_v2, eleven_turbo_v2_5kugel-3.5
eleven_multilingual_v1, eleven_multilingual_v2kugel-3.5
eleven_monolingual_v1kugel-3.5

You can also pass a KugelAudio model ID directly: kugel-3 or kugel-3.5. On both hosted regions, the ElevenLabs aliases map only to kugel-3.5. An on-premise deployment maps them to the model it was installed with.

Parameter Mapping

ElevenLabsKugelAudioNotes
voice_idvoice_idUse KugelAudio voice IDs
model_idmodelSee model table above
similarity_boostcfg_scaleNon-zero values use cfg_scale = 1.0 + (similarity_boost × 2.0), clamped to [1.2, 2.5]; 0 currently uses the native 2.0 default
stabilityNoneNot used
styleNoneAccepted for compatibility; not used
use_speaker_boostNoneAccepted for compatibility; not used

Troubleshooting

Bash
# Check server health
curl https://api.kugelaudio.com/11labs/health

# List voices
curl -H "xi-api-key: your-api-key" https://api.kugelaudio.com/11labs/v1/voices | jq '.voices[:5]'

# Test PCM TTS
curl -X POST https://api.kugelaudio.com/11labs/v1/text-to-speech/480 \
  -H "xi-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "model_id": "kugel-3.5"}' \
  --output test.pcm

# Test Open WebUI-style MP3 TTS
curl -X POST https://api.kugelaudio.com/11labs/v1/text-to-speech/480 \
  -H "xi-api-key: your-api-key" \
  -H "Accept: audio/mpeg" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "model_id": "kugel-3.5"}' \
  --output test.mp3