Vapi Integration
Use KugelAudio as a custom TTS provider in Vapi voice assistants: get an API key and voice ID, configure the assistant, set the audio format and troubleshoot.
On this page
KugelAudio has a built-in Vapi custom TTS endpoint, so no proxy server is needed. Point your Vapi assistant at our API and you're done.
Setup
1. Get your KugelAudio API key and a voice ID
- API key: open the KugelAudio dashboard, then go to Settings → API Keys.
- Voice ID: open the KugelAudio dashboard, go to Voices, pick a voice, and copy its numeric ID.
2. Configure your Vapi assistant
Use PATCH /assistant/{id} to update an existing assistant, or include the voice field when creating a new one with POST /assistant:
{
"voice": {
"provider": "custom-voice",
"server": {
"url": "https://api.kugelaudio.com/vapi/synthesize?voice_id=YOUR_VOICE_ID",
"secret": "YOUR_KUGELAUDIO_API_KEY",
"timeoutSeconds": 30
}
}
}voice_id: the numeric voice ID from Step 1.server.secret: your KugelAudio API key. Vapi sends it as thex-vapi-secretheader on every request, and KugelAudio authenticates it like any API key. This keeps the key out of the URL, which Vapi stores in the assistant config and may log.
- Open the assistant
In the Vapi dashboard, open the assistant you want to use.
- Go to Voice → Provider
Click Voice, then Provider.
- Pick Custom Provider
Scroll down in the provider list and select Custom Provider.
- Paste the URLText
https://api.kugelaudio.com/vapi/synthesize?voice_id=YOUR_VOICE_ID&api_key=YOUR_KUGELAUDIO_API_KEY - Save
Save the assistant. The voice is now powered by KugelAudio.
The dashboard flow puts the API key in the URL. Prefer the API flow with server.secret for production assistants.
No code, no extra server, no proxy.
How it works
Vapi sends one POST per phrase to /vapi/synthesize:
{
"message": {
"type": "voice-request",
"text": "Hello, how can I help you today?",
"sampleRate": 24000
}
}KugelAudio streams back raw PCM16 at the requested sample rate, which is what Vapi expects. message.sampleRate must be one of 8000, 16000,
22050, 24000, or 44100; unsupported rates are rejected with 400.
Audio format
| Parameter | Value |
|---|---|
| Format | Raw PCM (no WAV/container header) |
| Bit depth | 16-bit signed, little-endian |
| Channels | 1 (mono) |
| Sample rate | Matches message.sampleRate from Vapi's request |
Troubleshooting
401: authentication failed
Check the key in server.secret (or the api_key query parameter). For an
eu- key, point the URL at https://api.eu.kugelaudio.com/vapi/synthesize
and use the key without the eu- prefix: only the KugelAudio SDKs strip it
for you.
400: unsupported sample rate
Vapi's message.sampleRate must be 8000, 16000, 22050, 24000 or
44100. Change the assistant's audio settings in Vapi.
The assistant speaks with the wrong voice
The voice comes from the voice_id query parameter in the server URL, not
from Vapi's Voice ID field. Check the ID in Voices.