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

# Ultravox

> Use Kova TTS as the voice in your Ultravox Realtime agents.

[Ultravox](https://ultravox.ai) is a platform for real-time voice agents. Kova plugs in through Ultravox's **generic external-TTS adapter**: you point an agent straight at the Kova API, no Kova-side setup required, so this works today.

## Configure your agent

Set an `externalVoice` of type `generic` on call (or agent) creation, pointed at the Kova `/v1/tts` endpoint. Kova returns the audio base64-encoded inside a JSON body, so `jsonAudioFieldPath` and `jsonByteEncoding` tell Ultravox how to read it.

```json theme={null}
{
  "externalVoice": {
    "generic": {
      "url": "https://api.kova.ai/v1/tts",
      "headers": {
        "x-api-key": "kova_sk_your_key_here",
        "Content-Type": "application/json"
      },
      "body": {
        "text": "{text}",
        "voice": "ash",
        "response_format": { "encoding": "pcm", "sample_rate": 24000 }
      },
      "responseSampleRate": 24000,
      "responseMimeType": "application/jsonl",
      "jsonAudioFieldPath": "audio"
    }
  }
}
```

* **`body.text`**: keep it as `"{text}"`. Ultravox replaces it with the agent's text on each turn.
* **`body.voice`**: any speaker id from [`/v1/tts/speakers`](/voices), for example `ash`.
* **`body.response_format`**: `encoding: "pcm"` returns raw 16-bit mono little-endian PCM. Keep `sample_rate` equal to `responseSampleRate`.
* **`responseMimeType` / `jsonAudioFieldPath`**: Kova returns `{ "audio": "<base64>" }`, so Ultravox treats the response as JSON, reads the `audio` field, and base64-decodes it. This exact config is validated end to end against Ultravox Realtime.
* **`headers.x-api-key`**: your Kova API key from [platform.kova.ai](https://platform.kova.ai/dashboard/api-keys). Ultravox sends it on every request; Kova validates and bills it.

<Note>`externalVoice` is mutually exclusive with the `voice` field, set one or the other. Each config maps to one Kova voice; create one `externalVoice` per voice you want to offer.</Note>

## Billing and errors

Usage is billed to the API key in the `x-api-key` header, the same as direct API calls. An invalid key returns 401; an account out of credits returns 402. Top up at [platform.kova.ai/dashboard/billing](https://platform.kova.ai/dashboard/billing).