Live streaming

Endpoint: wss://api.aircaps.com/v1/realtime

Protocol

Connect

Open the WebSocket with your key in the handshake header: Authorization: Bearer aircaps_sk_...

Send start

The first message is JSON. language accepts en and regional variants such as en-US; multilingual support is planned.

{
  "type": "start",
  "providers": ["a5sv2"],
  "encoding": "pcm_s16le",
  "sample_rate": 16000,
  "channels": 1,
  "language": "en-US"
}

Wait for ready

The server may send provider_status messages while capacity starts (up to about a minute after quiet periods), then ready. Do not send audio before ready.

Stream audio

Send binary frames of mono 16 kHz signed 16-bit little-endian PCM, in real time. 20 ms frames (640 bytes) are recommended; frames may be at most 64 KB. Send {"type": "ping"} to keep an idle connection open.

Finish

Send {"type": "finish"}. The server sends the final transcript, then a finished message, and closes.

Messages from the server

{"type": "transcript", "provider": "a5sv2", "text": "the complete current transcript", "is_final": false}

text is always the complete transcript so far; replace what you display rather than appending.

type	Meaning
`provider_status`	Startup progress (`message`)
`ready`	Start sending audio. Includes `session_limit_ms`
`transcript`	Current text; `is_final` is true when a segment is settled
`session_limit`	The 5-minute session or your usage limit was reached
`error`	`code` and `message`; the connection then closes
`finished`	`audio_ms` streamed and `billed_ms` counted toward usage
`pong`	Reply to `ping`

Custom vocabulary

Bias recognition toward names and terms with up to 64 entries, each with a strength from 0 to 12:

{
  "type": "start",
  "providers": ["a5sv2"],
  "custom_vocabulary_enabled": true,
  "custom_vocabulary": [{"text": "AirCaps", "strength": 6}]
}

Rules

Audio must arrive in real time; sending faster (beyond a 2-second burst) closes the session with realtime_rate_exceeded.
A session ends after 5 minutes; open a new one to continue.
No audio for 45 seconds closes the session.
At most 5 sessions per account at once.

Close codes

Code	Meaning
1000	Normal close after `finished`
4400	Bad start message or frame, including `unsupported_language`
4401	Missing or invalid API key
4403	Origin not allowed (browsers), or the account has no access to this model (`model_access_denied`)
4408	Idle timeout
4409	Usage limit, session limit, rate or frame size (talk to sales to raise limits)
1013	Temporarily unavailable; retry
1011	Server error

See the Python sample.

Get started

Guides

Operations

Protocol

Messages from the server

Custom vocabulary

Rules

Close codes

​Protocol

​Messages from the server

​Custom vocabulary

​Rules

​Close codes

Protocol

Messages from the server

Custom vocabulary

Rules

Close codes