Skip to main content
Ultravox 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. 
{
  "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, 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. Ultravox sends it on every request; Kova validates and bills it.
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.

​
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.