Realtime Text to Speech v3

Realtime TTS v3 is the recommended WebSocket protocol for new integrations. Kitta AI, MiniMax, and future realtime engines share the same camelCase events, authentication, billing, and recovery flow. Switching engines changes modelId; it does not require provider-specific client code.

Endpoint and discovery

All application messages are MessagePack binary frames, not JSON text frames. Read capabilities before connecting. It returns currently enabled public models, controls, formats, transport limits, and modes without exposing physical routing.

Authentication

Backend clients send the API key during the WebSocket handshake:

Authorization: Bearer API_KEY
Sec-WebSocket-Protocol: realtime.tts.msgpack.v3

Do not put credentials in the URL. Browsers cannot set the Authorization header; a trusted backend must create an origin-bound, one-time ticket with POST /v3/tts/browser-tickets, then use the returned WebSocket URL and subprotocol.

The browser connects with the returned URL and subprotocol, then sends { event: 'auth', token: 'rtv2_ticket_...' } as its first MessagePack frame.

Start a session

{
  event: 'start',
  eventId: 'event-1',
  mode: 'simple',
  request: {
    voiceId: '00a1b221-6137-4b73-ad62-b0cbce134167',
    modelId: 'fishaudio-s21pro-flash',
    format: 'mp3',
    speed: 1,
    volume: 0,
    stability: 1,
    similarity: 1,
    language: 'en',
    textNormalization: true,
    chunkLength: 200,
    latency: 'balanced'
  }
}

voiceId and modelId are required. The selected voice must support that public model. Supported product controls and formats come from capabilities. Unknown or unsupported controls are ignored with structured warnings; ready.effectiveRequest is the authoritative normalized request.

The server answers with a ready event containing protocolVersion, sessionId, requestId, modelId, voiceId, format, effectiveRequest, and any warnings.

Send text and receive audio

Simple mode can submit and commit text in one event:

{ event: 'input', eventId: 'event-2', text: 'Hello, world.', commit: true }

For explicit segmentation, send input with commit: false and then flush; reliable mode also supports sequenced text events. End the session with { event: 'stop' }. Use { event: 'ping', timestamp: Date.now() } for an application heartbeat.

Important server events are authenticated, ready, input_ack, segment_accepted, audio, usage, segment_completed, request_status, warning, error, finish, and pong. The audio.audio value is binary data. Every v3 response uses camelCase.

Reliable mode and recovery

Use mode: 'reliable' with a stable requestId. Reconnect and repeat the same normalized request to recover or replay its status; do not reuse the ID with different parameters.

GET /v3/tts/requests/{requestId}
GET /v3/tts/requests/{requestId}/segments/{segmentId}/audio
Authorization: Bearer API_KEY

The status response includes state, retryable, units, resultAvailable, and segment metadata in camelCase. Recovery audio is available only when resultAvailable and the segment response indicate a stored result.

Errors and compatibility

Handle the structured error fields code, message, retryable, terminal, and optional stage/path. Connection failures can also return HTTP errors before upgrade. Retry only when retryable is true, preserve requestId, and use backoff.

Realtime v2 at /v2/tts/live remains supported. Its snake_case event contract and realtime.tts.msgpack.v2 subprotocol are unchanged. Do not mix v2 fields and v3 fields in one client. See the migration guide.