KugelAudio natively supports the ElevenLabs API format, allowing you to use any application built for the ElevenLabs API. Simply change the base_url to your KugelAudio server and your existing code works.
Why Use ElevenLabs Compatibility?
- Drop-in replacement: Use existing ElevenLabs integrations without code changes
- SDK compatibility: Works with the official ElevenLabs Python SDK
- Streaming support: Full support for streaming TTS
- No proxy needed: ElevenLabs endpoints are built directly into the TTS server
Quick Start
Start the TTS Server
cd tts
uv run python -m src.serving.server_ray --model 1.5b --port 8000
Use the ElevenLabs SDK
from elevenlabs import ElevenLabs
# Point directly to your KugelAudio server
client = ElevenLabs(
api_key="your-kugelaudio-api-key",
base_url="http://localhost:8000"
)
# Use exactly like ElevenLabs!
audio = client.text_to_speech.convert(
voice_id="268", # Your KugelAudio voice ID
text="Hello from KugelAudio!",
model_id="kugel-1-turbo",
output_format="pcm_24000",
)
# Save the audio
with open("output.pcm", "wb") as f:
for chunk in audio:
f.write(chunk)
Limitations
This is a compatibility layer for basic TTS use cases, not a full ElevenLabs API implementation.
- Voice cloning endpoints (
/v1/voices/add, /v1/voices/{voice_id}/edit)
- Sound generation (
/v1/sound-generation)
- Audio isolation (
/v1/audio-isolation)
- Speech-to-speech (
/v1/speech-to-speech)
- Dubbing endpoints
- Projects API
- Pronunciation dictionaries
- WebSocket input streaming (
/v1/text-to-speech/{voice_id}/stream-input)
- MP3 output format (use PCM and convert client-side)
Stub endpoints (return empty/default data):
/v1/history - Returns empty history/v1/user - Returns default subscription info
Usage Examples
Python SDK - Basic
from elevenlabs import ElevenLabs
client = ElevenLabs(
api_key="your-api-key",
base_url="http://localhost:8000"
)
# List available voices
voices = client.voices.get_all()
for voice in voices.voices:
print(f"{voice.voice_id}: {voice.name} ({voice.category})")
# List available models
models = client.models.list()
for model in models:
print(f"{model.model_id}: {model.name}")
Streaming TTS
from elevenlabs import ElevenLabs
client = ElevenLabs(
api_key="your-api-key",
base_url="http://localhost:8000"
)
# Stream audio chunks for low-latency playback
audio_stream = client.text_to_speech.convert(
voice_id="268",
text="This is streaming audio from KugelAudio.",
model_id="kugel-1-turbo",
output_format="pcm_24000",
)
for chunk in audio_stream:
# Play or process each chunk
process_audio(chunk)
Voice Settings
from elevenlabs import ElevenLabs, VoiceSettings
client = ElevenLabs(
api_key="your-api-key",
base_url="http://localhost:8000"
)
# Customize voice settings
audio = client.text_to_speech.convert(
voice_id="268",
text="Hello with custom settings!",
model_id="kugel-1-turbo",
output_format="pcm_24000",
voice_settings=VoiceSettings(
stability=0.5,
similarity_boost=0.75, # Maps to cfg_scale
),
)
Supported Endpoints
Text-to-Speech
| Endpoint | Method | Status |
|---|
/v1/text-to-speech/{voice_id} | POST | ✅ Supported |
/v1/text-to-speech/{voice_id}/stream | POST | ✅ Supported |
/v1/text-to-speech/{voice_id}/stream-input | WebSocket | ❌ Not supported |
Voices
| Endpoint | Method | Status |
|---|
/v1/voices | GET | ✅ Supported |
/v1/voices/{voice_id} | GET | ✅ Supported |
/v1/voices/add | POST | ❌ Not supported |
/v1/voices/{voice_id}/edit | POST | ❌ Not supported |
Models & User
| Endpoint | Method | Status |
|---|
/v1/models | GET | ✅ Supported |
/v1/user | GET | ⚠️ Stub (returns defaults) |
/v1/user/subscription | GET | ⚠️ Stub (returns defaults) |
/v1/history | GET | ⚠️ Stub (returns empty) |
Available Models
| Model ID | Name | Description |
|---|
kugel-1-turbo | Kugel 1 Turbo | Fast 1.5B model, optimized for low latency |
kugel-1 | Kugel 1 | Premium 7B model, exceptional voice quality |
Parameter Mapping
| ElevenLabs | KugelAudio | Notes |
|---|
voice_id | voice_id | Use KugelAudio voice IDs (not ElevenLabs IDs) |
model_id | model | Use kugel-1-turbo or kugel-1 |
similarity_boost | cfg_scale | Mapped: cfg_scale = 1.0 + (similarity_boost * 2.0) |
stability | - | Not used |
output_format | - | Only PCM formats supported |
| Format | Status |
|---|
pcm_24000 | ✅ Recommended (native) |
pcm_22050 | ✅ Supported |
pcm_16000 | ✅ Supported |
pcm_8000 | ✅ Supported |
mp3_* | ❌ Not supported |
ulaw_* | ❌ Not supported |
Audio is generated natively at 24kHz. Lower sample rates use server-side resampling with minimal latency impact (~0.1ms per chunk).
Migrating from ElevenLabs
Step 1: Start KugelAudio Server
cd tts
uv run python -m src.serving.server_ray --model 1.5b --port 8000
Step 2: Update Your Code
Change only the base_url:
# Before (ElevenLabs)
client = ElevenLabs(
api_key="your-elevenlabs-key",
)
# After (KugelAudio)
client = ElevenLabs(
api_key="your-kugelaudio-key",
base_url="http://localhost:8000"
)
Step 3: Update Voice IDs
You must use KugelAudio voice IDs, not ElevenLabs voice IDs:
voices = client.voices.get_all()
for voice in voices.voices:
print(f"{voice.voice_id}: {voice.name}")
# Before
audio = client.text_to_speech.convert(
voice_id="...",
text="...",
output_format="mp3_44100_128", # Won't work
)
# After
audio = client.text_to_speech.convert(
voice_id="...",
text="...",
output_format="pcm_24000", # Use PCM
)
Troubleshooting
Check Server Health
curl http://localhost:8000/health
List Available Voices
curl http://localhost:8000/v1/voices | jq '.voices[:3]'
Test TTS Generation
curl -X POST http://localhost:8000/v1/text-to-speech/268 \
-H "Content-Type: application/json" \
-d '{"text": "Hello world", "model_id": "kugel-1-turbo"}' \
--output test.pcm
Next Steps
