Skip to content
KugelAudioDocs

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

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:

JSON
{
  "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 the x-vapi-secret header 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.

No code, no extra server, no proxy.

How it works

Vapi sends one POST per phrase to /vapi/synthesize:

JSON
{
  "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

ParameterValue
FormatRaw PCM (no WAV/container header)
Bit depth16-bit signed, little-endian
Channels1 (mono)
Sample rateMatches 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.

Next steps