Kova TTS for AI agents

https://docs.kova.ai/for-agents.md

{
  "text": "Hello from Kova.",
  "voice": "cal",
  "response_format": { "encoding": "mp3", "sample_rate": 32000, "bitrate": "128k" },
  "timestamps": false,
  "temperature": 1.0,
  "normalize_text": false
}

{ "encoding": "mp3", "sample_rate": 32000, "bitrate": "128k" }

curl https://api.kova.ai/v1/tts \
  -H "x-api-key: $KOVA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"Hello from Kova.","voice":"cal","response_format":{"encoding":"mp3"}}' \
  | jq -r .audio | base64 -d > out.mp3

{
  "audio": "<base64>",
  "timestamps": {
    "words": ["Hello", "from", "Kova."],
    "start_seconds": [0.06, 0.23, 0.53],
    "end_seconds": [0.1, 0.38, 0.76]
  }
}

data: {"type":"audio","audio_chunk":"<base64>"}

data: {"type":"timestamps","words":["Hello"],"start_seconds":[0.06],"end_seconds":[0.1]}

data: {"type":"audio","audio_chunk":"<base64>"}

type AudioEvent = { type: "audio"; audio_chunk: string };   // base64, your response_format
type TimestampsEvent = {
  type: "timestamps";
  words: string[];
  start_seconds: number[];
  end_seconds: number[];
};

import base64, json, httpx

audio = bytearray()
words = []
with httpx.Client(timeout=180) as c:
    with c.stream("POST", "https://api.kova.ai/v1/tts/stream",
                  json={"text": "Hello from Kova.", "voice": "cal",
                        "response_format": {"encoding": "mp3"}, "timestamps": True},
                  headers={"x-api-key": KEY}) as r:
        r.raise_for_status()
        buf = b""
        for chunk in r.iter_bytes():
            buf += chunk
            while b"\n\n" in buf:
                record, buf = buf.split(b"\n\n", 1)
                if not record.strip():
                    continue
                ev = json.loads(record[len(b"data: "):])
                if ev["type"] == "audio":
                    audio.extend(base64.b64decode(ev["audio_chunk"]))
                elif ev["type"] == "timestamps":
                    words.extend(ev["words"])          # append, never replace
open("out.mp3", "wb").write(audio)

curl https://api.kova.ai/v1/tts/speakers -H "x-api-key: $KOVA_API_KEY"

{"speaker_ids":["cal","owen","ash","mira","theo","tess","paul","mira_conv","ash_conv"]}

// Open a context. voice_id and model_id are both REQUIRED.
{ start_context: {
    voice_id: string;
    model_id: string;
    timestamps?: boolean;          // default false
    temperature?: number | null;   // 0.5-3.0
    response_format?: { encoding: string; sample_rate?: number; bitrate?: string | number };
  },
  context_id?: string | null }

{ send_text: string; context_id?: string | null }               // append text
{ flush: true; context_id?: string | null; flush_id?: string | null }
{ close_context: true; context_id?: string | null }

{ context_started: { voice_id, model_id, timestamps, response_format }, context_id }
{ audio_chunk: string; context_id }        // base64
{ timestamps: { words, start_seconds, end_seconds }, context_id }
{ flush_completed: true; flush_id: string; context_id }
{ context_closed: true; context_id }
{ error: string; context_id?; flush_id? }

import asyncio, json, base64, ssl, certifi, websockets

async def main():
    ctx = ssl.create_default_context(cafile=certifi.where())
    audio = bytearray()
    async with websockets.connect("wss://api.kova.ai/v1/tts/ws",
                                  additional_headers={"x-api-key": KEY},
                                  ssl=ctx, max_size=None) as ws:
        await ws.send(json.dumps({"start_context": {
            "voice_id": "cal", "model_id": "default", "timestamps": True,
            "response_format": {"encoding": "pcm", "sample_rate": 32000}},
            "context_id": "c1"}))
        await ws.send(json.dumps({"send_text": "Welcome to Kova. ", "context_id": "c1"}))
        await ws.send(json.dumps({"send_text": "Second sentence.", "context_id": "c1"}))
        await ws.send(json.dumps({"flush": True, "context_id": "c1", "flush_id": "f1"}))

        async for raw in ws:
            f = json.loads(raw)
            if "audio_chunk" in f:
                audio.extend(base64.b64decode(f["audio_chunk"]))
            elif "flush_completed" in f and f.get("flush_id") == "f1":
                break                      # match YOUR flush_id, not any flush_completed
        await ws.send(json.dumps({"close_context": True, "context_id": "c1"}))

    import wave                            # pcm is headerless; add a WAV header yourself
    with wave.open("out.wav", "wb") as w:
        w.setnchannels(1); w.setsampwidth(2); w.setframerate(32000)
        w.writeframes(bytes(audio))

asyncio.run(main())

{
  "error": "unknown_voice",
  "message": "Unknown voice 'nope'. Valid voices: ash, ash_conv, cal, mira, mira_conv, owen, paul, tess, theo",
  "voice": "nope",
  "valid_voices": ["ash", "ash_conv", "cal", "mira", "mira_conv", "owen", "paul", "tess", "theo"]
}

Value error, Unsupported audio encoding: flac
Value error, mp3 audio sample_rate must be between 16000 and 48000 Hz
Value error, opus audio sample_rate must be one of 8000, 12000, 16000, 24000, or 48000 Hz
Value error, mulaw audio requires an 8000 Hz sample rate
Value error, mp3 audio bitrate must be between 32kbps and 320kbps
Value error, opus audio bitrate must be between 32kbps and 192kbps
Value error, wav audio does not support a bitrate option
Value error, Invalid mp3 audio bitrate: abc
Input should be greater than or equal to 0.5          (temperature)
Input should be less than or equal to 3               (temperature)
Extra inputs are not permitted                        (unknown field)