API conventions

Base URLs

Use the following base URL for HTTP SDKs:

https://api.kittenml.com/v1

Use complete endpoint URLs with cURL or a generic HTTP client:

https://api.kittenml.com/v1/audio/transcriptions
https://api.kittenml.com/v1/audio/speech

Realtime STT uses a secure WebSocket URL:

wss://api.kittenml.com/v1/realtime

Incremental-input TTS also uses a secure WebSocket URL:

wss://api.kittenml.com/v1/tts/realtime

Authentication

Send a KittenML API key as a bearer token:

Authorization: Bearer sk_kitten_live_...

Authentication occurs once when an HTTP request or realtime session starts. It does not run for every WebSocket audio append.

Request bodies

• Upload transcription uses multipart/form-data.
• Speech generation uses application/json.
• Realtime WebSocket client messages are JSON. Audio bytes are base64 encoded inside input_audio_buffer.append events.

Response bodies

• JSON responses use application/json.
• Plain transcripts and subtitles use text content types.
• Upload streaming uses finite Server-Sent Events (SSE) with text/event-stream.
• TTS uses chunked binary audio by default, or finite SSE when requested.
• Incremental-input TTS exchanges JSON WebSocket events and returns Base64 24 kHz PCM audio deltas.
• Realtime transcripts arrive as WebSocket JSON events.

Request IDs

HTTP responses include an x-request-id header. JSON transcription bodies and realtime events also include request_id. Retain it when logging a failure or contacting support.

Errors

The core routes use standard HTTP status codes. Authentication, model, and service errors use a structured JSON envelope. See Errors and retries for response shapes and retry guidance.

Retries

• Do not retry an unchanged 400, 401, 402, or 404 request.
• For 429, wait at least the number of seconds in Retry-After, then retry with backoff and jitter.
• Retry transient 502, 503, other 5xx, and network failures with capped exponential backoff.
• A new client request is a new inference. Do not assume resubmitting it is deduplicated.

API versioning

The stable public routes are under /v1. KittenML does not currently require a dated version header.