> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vapi Integration

> Use KugelAudio as a custom TTS provider in Vapi voice assistants

KugelAudio has a built-in [Vapi custom TTS](https://docs.vapi.ai/customization/custom-voices/custom-tts) endpoint — no proxy server needed. Just point your Vapi assistant at our API and you're done.

## Setup

### 1. Get your KugelAudio API key and a voice ID

* **API key** — find it in the [KugelAudio dashboard](https://app.kugelaudio.com/settings/api-keys) under Settings → API Keys.
* **Voice ID** — open the [Voices page](https://app.kugelaudio.com/voices), pick a voice, and copy its numeric ID.

### 2. Configure your Vapi assistant

Pick whichever flow you prefer — the dashboard is faster for one-offs, the API is better for scripted setup.

<Tabs>
  <Tab title="Vapi Dashboard">
    <Steps>
      <Step title="Open the assistant">
        In the Vapi dashboard, open the assistant you want to use.
      </Step>

      <Step title="Go to Voice → Provider">
        Click **Voice**, then **Provider**.
      </Step>

      <Step title="Pick Custom Provider">
        Scroll down in the provider list and select **Custom Provider**.
      </Step>

      <Step title="Paste the URL">
        ```
        https://api.kugelaudio.com/vapi/synthesize?voice_id=YOUR_VOICE_ID&api_key=YOUR_KUGELAUDIO_API_KEY
        ```
      </Step>

      <Step title="Save">
        Save the assistant. The voice is now powered by KugelAudio.
      </Step>
    </Steps>

    <Warning>
      The "Voice ID" field inside Vapi's UI has no effect when using a custom provider — the `voice_id` query param in the URL is what selects the voice.
    </Warning>
  </Tab>

  <Tab title="Vapi API">
    Use `PATCH /assistant/{id}` to update an existing assistant, or include the `voice` field when creating a new one with `POST /assistant`:

    ```json theme={null}
    {
      "voice": {
        "provider": "custom-voice",
        "server": {
          "url": "https://api.kugelaudio.com/vapi/synthesize?voice_id=YOUR_VOICE_ID&api_key=YOUR_KUGELAUDIO_API_KEY",
          "timeoutSeconds": 30
        }
      }
    }
    ```

    * `voice_id` — the numeric voice ID from Step 1.
    * `api_key` — your KugelAudio API key. KugelAudio authenticates it on every request.

    <Note>
      As an alternative, you can pass the API key in Vapi's `server.secret` field instead of the URL. Vapi will send it as the `x-vapi-secret` header on every request and KugelAudio will authenticate it the same way.
    </Note>
  </Tab>
</Tabs>

That's it. No code, no extra server, no proxy.

<Tip>
  To select a specific model, add `&model_id=kugel-3` (recommended) or `&model_id=kugel-3` (lowest latency) to the URL.
</Tip>

## How it works

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

```json theme={null}
{
  "message": {
    "type": "voice-request",
    "text": "Hello, how can I help you today?",
    "sampleRate": 24000
  }
}
```

KugelAudio streams back raw PCM16 at the requested sample rate — exactly what Vapi expects.

## 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 |