WebSocket frames

Frames are JSON objects sent as WebSocket text messages in both directions. The frame type is identified by which discriminator key is present (start_context, send_text, audio_chunk, and so on).

Client → Server frames

start_context

Opens a new context. The server replies with context_started.

type StartContext = {
  start_context: {
    voice_id: string;                                              // REQUIRED
    model_id: string;                                              // REQUIRED
    temperature?: number | null;                                   // 0.5-3.0
    timestamps?: boolean;                                          // default false
    response_format?: {
      encoding: "mp3" | "pcm" | "wav" | "linear16" | "opus" | "mulaw" | "alaw";
      sample_rate?: number;
      bitrate?: string | number;
    };
  };
  context_id?: string | null;                                       // your id; echoed on all frames
};

Example:

{
  "start_context": {
    "voice_id": "cal",
    "model_id": "default",
    "timestamps": true,
    "response_format": {"encoding": "pcm", "sample_rate": 32000}
  },
  "context_id": "ctx-greet"
}

Both voice_id and model_id are required. Omitting either returns an error frame containing the raw validation message:

{"error": "invalid frame: 1 validation error for StartContext\nstart_context.model_id\n  Field required ..."}

model_id is required. Send "default" — it is echoed back on context_started.

An unknown voice_id returns a clean error frame rather than tearing down the connection:

{"error": "start_context failed: Unknown voice 'not_a_voice'. Valid voices: ash, ash_conv, cal, mira, mira_conv, owen, paul, tess, theo", "context_id": "c1"}

send_text

Appends text to an open context. The server begins generating incrementally.

type SendText = {
  send_text: string;
  context_id?: string | null;
};

{"send_text": "Welcome to Kova. ", "context_id": "ctx-greet"}

Sending text for a context that was never started returns {"error": "unknown context_id: ..."}.

Include trailing whitespace when you send consecutive fragments ("Welcome to Kova. ") so the model treats them as sequential prose rather than concatenated tokens.

flush

Marks the end of the current utterance. The server finishes in-progress generation and emits flush_completed.

type Flush = {
  flush: true;
  context_id?: string | null;
  flush_id?: string | null;     // optional; echoed on flush_completed
};

{"flush": true, "context_id": "ctx-greet", "flush_id": "f1"}

flush_id is optional — if you omit it the server generates a UUID and returns that in flush_completed (e.g. "060c4b09-7462-4fb5-ae89-cfc85121ea58"). Always send your own so you can match the reply to the request.

close_context

Releases server resources for a context. The WebSocket itself stays open and remains usable for new contexts.

type CloseContext = {
  close_context: true;
  context_id?: string | null;
};

close_context emits two frames, not one. First a flush_completed whose flush_id is the synthetic string "<context_id>:close", then context_closed:

{"flush_completed": true, "context_id": "c1", "flush_id": "c1:close"}
{"context_closed": true, "context_id": "c1"}

Closing also flushes any text you sent but never flushed, so audio can continue arriving after you request the close. If your read loop breaks on any flush_completed, it will exit early on this synthetic one — match on your own flush_id values instead.

Closing a context that doesn’t exist returns {"error": "unknown context_id: ..."}.

Server → Client frames

context_started

Sent after a successful start_context.

type ContextStarted = {
  context_started: {
    voice_id: string;
    model_id: string;
    timestamps: boolean;
    response_format: object;
  };
  context_id?: string | null;
};

response_format here is fully resolved, including defaults you didn’t send. Starting a context with {"encoding":"mp3"} echoes back {"encoding":"mp3","sample_rate":32000,"bitrate":"128k"}. Read the format from this frame rather than assuming — it’s the authoritative answer for how to interpret the bytes that follow.

audio_chunk

Audio bytes for a context.

type AudioChunk = {
  audio_chunk: string;          // base64-encoded
  context_id?: string | null;
};

Default when no response_format is set: base64-encoded headerless signed 16-bit little-endian PCM, 32000 Hz, mono. As on the streaming HTTP endpoint, mp3 over WebSocket arrives as raw MPEG frames with no ID3 header.

timestamps

Word timing, sent only when the context was started with timestamps: true.

type Timestamps = {
  timestamps: {
    words: string[];
    start_seconds: number[];
    end_seconds: number[];
  };
  context_id?: string | null;
};

Timestamps arrive incrementally, one to three words per frame, exactly as on the streaming HTTP endpoint. Append them in arrival order; never overwrite. start_seconds are absolute offsets from the start of the utterance.

flush_completed

Emitted after every audio_chunk for the flushed utterance has been sent.

type FlushCompleted = {
  flush_completed: true;
  flush_id: string;
  context_id?: string | null;
};

flush_id is your value, a server-generated UUID if you omitted one, or the synthetic "<context_id>:close" when triggered by close_context.

context_closed

Confirms a context has been released. Always preceded by a flush_completed.

type ContextClosed = {
  context_closed: true;
  context_id?: string | null;
};

error

A server-side error scoped to a context or flush.

type ErrorFrame = {
  error: string;
  context_id?: string | null;
  flush_id?: string | null;
};

error frames are not fatal. The socket stays open and other contexts keep working normally. The one exception is an authentication failure, which sends {"error": "INVALID_API_KEY"} and then closes the connection with code 1008 (policy violation).

Observed messages:

unknown context_id: c1
start_context failed: Unknown voice 'not_a_voice'. Valid voices: ash, ash_conv, cal, ...
invalid frame: 1 validation error for StartContext ...
INVALID_API_KEY

context_id is optional

Every frame’s context_id may be omitted. A session with no context_id anywhere works fine, and server frames come back with no context_id key at all. Set it explicitly whenever you might run more than one context on a connection — it’s the only way to demultiplex.

Frame ordering

Within a single context_id:

context_started arrives before any audio_chunk or timestamps.
audio_chunk and timestamps interleave freely during generation, in no fixed ratio.
flush_completed arrives after the last audio_chunk for that utterance.
context_closed arrives last, always immediately after a flush_completed.

Frames from different contexts interleave freely and fairly. With two contexts generating at once, audio chunks alternate steadily between them — demultiplex on context_id.

Worked multi-context example

Two contexts, different voices and different formats, on one connection:

{"start_context": {"voice_id": "cal",  "model_id": "default", "response_format": {"encoding": "mp3"}}, "context_id": "A"}
{"start_context": {"voice_id": "mira", "model_id": "default", "response_format": {"encoding": "pcm", "sample_rate": 16000}}, "context_id": "B"}
{"send_text": "Context A speaking.", "context_id": "A"}
{"send_text": "Context B speaking.", "context_id": "B"}
{"flush": true, "context_id": "A", "flush_id": "fa"}
{"flush": true, "context_id": "B", "flush_id": "fb"}

The server replies with two context_started frames carrying each context’s resolved format, then interleaved audio_chunk frames tagged A and B, then a flush_completed for each.

Get started

HTTP API

WebSocket API

Voices

Integrations

SDKs

Reference

WebSocket frames

Client → Server frames

start_context

send_text

flush

close_context

Server → Client frames

context_started

audio_chunk

timestamps

flush_completed

context_closed

error

context_id is optional

Frame ordering

Worked multi-context example

See also

​Client → Server frames

​start_context

​send_text

​flush

​close_context

​Server → Client frames

​context_started

​audio_chunk

​timestamps

​flush_completed

​context_closed

​error

​context_id is optional

​Frame ordering

​Worked multi-context example

​See also

Client → Server frames

start_context

send_text

flush

close_context

Server → Client frames

context_started

audio_chunk

timestamps

flush_completed

context_closed

error

context_id is optional

Frame ordering

Worked multi-context example

See also