API reference

Streaming speech recognition, with a small and explicit surface.

Use the REST API to create short-lived WebSocket sessions for Kikuyu and Dholuo ASR. Permanent API keys belong only on a trusted server.

Endpoints

GET/v1/models

List the available streaming ASR models and audio format.

Public

POST/v1/asr/sessions

Reserve audio credits and create a short-lived, one-use WebSocket credential.

Bearer API key

GET/v1/usage

Read the current credit balance and recent ASR usage.

Bearer API key

Create an ASR session

Send Authorization: Bearer celo_live_v1_… and optionally a unique Idempotency-Key. The request sets an upper bound of 1 to 300 audio seconds.

POST /v1/asr/sessions
Content-Type: application/json
Authorization: Bearer celo_live_v1_…
Idempotency-Key: 0f1d884f-8bb8-4ca0-b6b5-80ca196d4091

{
  "model": "celo-asr-kikuyu-v1",
  "max_audio_seconds": 60
}

Model is either celo-asr-kikuyu-v1 or celo-asr-dholuo-v1. Successful responses contain the WSS URL, two subprotocol values, expiry, reserved credits, and actual audio limit. If at least one second remains but the available balance is below the requested maximum, use the returned audio.max_audio_seconds and credits.reserved as the actual session limit.

WebSocket protocol

Open websocket_url with both values from websocket_protocols, in order. The second value is a one-use secret and must not be logged. A status event may arrive while the session initializes; wait for ready, then send mono, 16 kHz, little-endian signed PCM16 as binary frames no larger than 65,536 bytes.

Client → server

{"type":"config"} with optional language and context fields
Binary PCM16 audio frames
{"type":"flush"}
{"type":"reset"}

Server → client

status may arrive while the session initializes
ready with stream configuration
config and reset acknowledgements
delta with an evolving transcript
final or error

Errors

REST errors include a stable code, a safe message, and an request_id. Keep that identifier when contacting support; never send your API key or session credential. Responses also include X-Request-Id; honor Retry-After on 429 and 503 responses.

HTTP	Code/type	Meaning
400	invalid_request_error	Malformed JSON or invalid parameters.
401	authentication_error	Missing, invalid, expired, or revoked key.
402	insufficient_credits	Not enough audio credit to reserve a session.
403	permission_error	Account inactive or model scope denied.
404	model_not_found	The requested ASR model does not exist.
409	idempotency_conflict	Idempotency key reused incompatibly.
413	request_too_large	JSON request body exceeds 16 KiB.
415	unsupported_media_type	Content-Type is not application/json.
429	rate_limit_error	Session or concurrency limit reached.
503	api_error	Service temporarily unavailable.

Machine-readable specifications

Use the OpenAPI document for REST tooling and the AsyncAPI document for WebSocket message schemas.

OpenAPI 3.1 JSON AsyncAPI 3.1 JSON