> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aircaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime stream

> Live transcription with A5S v2 Streaming over a WebSocket.

**WSS** `wss://api.aircaps.com/v1/realtime`

Requires access to A5S v2 Streaming. For a walkthrough, see [Live streaming](/guides/streaming).

## Connection

<ParamField header="Authorization" type="string" required>
  `Bearer aircaps_sk_...`, sent with the WebSocket handshake.
</ParamField>

The flow: connect, send `start`, wait for `ready`, stream binary audio, send `finish`, then receive `finished`. The server then closes with `1000`.

## Client messages

### start

The first message, as a JSON text frame.

<ParamField body="type" type="string" required>`"start"`</ParamField>

<ParamField body="language" type="string" default="en-US">
  Language of the audio. English only today: `en` or a regional variant (`en-US`, `en-GB`, `en-AU`, `en-CA`, `en-IN`, `en-IE`, `en-NZ`, `en-ZA`). Any other value is refused with `unsupported_language`. Multilingual support is planned.
</ParamField>

<ParamField body="encoding" type="string" default="pcm_s16le">Only `pcm_s16le` (signed 16-bit little-endian PCM).</ParamField>
<ParamField body="sample_rate" type="integer" default="16000">Only `16000`.</ParamField>
<ParamField body="channels" type="integer" default="1">Only `1` (mono).</ParamField>
<ParamField body="providers" type="string[]" default="[&#x22;a5sv2&#x22;]">The streaming engine. Only `"a5sv2"`.</ParamField>
<ParamField body="custom_vocabulary_enabled" type="boolean" default="false">Bias recognition toward `custom_vocabulary`.</ParamField>

<ParamField body="custom_vocabulary" type="object[]">
  Up to 64 terms.

  <Expandable title="properties">
    <ParamField body="text" type="string" required>A word or phrase, up to 100 characters.</ParamField>
    <ParamField body="strength" type="integer">Bias strength, 0 to 12.</ParamField>
  </Expandable>
</ParamField>

```json Example theme={null}
{"type": "start", "language": "en-US", "encoding": "pcm_s16le", "sample_rate": 16000, "channels": 1,
 "custom_vocabulary_enabled": true, "custom_vocabulary": [{"text": "AirCaps", "strength": 6}]}
```

### Audio

Binary frames of raw PCM in the `start` format. Send them after `ready`, in real time; a 2-second burst is allowed. 20 ms frames (640 bytes) are recommended. A frame can be at most 64 KB.

### ping

`{"type": "ping"}`. The server answers `pong`.

### finish

`{"type": "finish"}`. The server flushes the final transcript, sends `finished`, and closes.

## Server messages

Each is a JSON text frame with a `type`.

### provider\_status

Startup progress. Starting capacity can take up to about a minute after a quiet period.

<ResponseField name="message" type="string">For example `"Getting things ready, please hold on (1 min)"`.</ResponseField>

### ready

Start sending audio.

<ResponseField name="session_limit_ms" type="integer">Maximum audio for this session: 5 minutes, or less if little usage remains.</ResponseField>
<ResponseField name="quota_ms" type="integer">The account's usage limit, in milliseconds.</ResponseField>
<ResponseField name="used_ms" type="integer">Usage so far, in milliseconds.</ResponseField>
<ResponseField name="language" type="string">`"en-US"`</ResponseField>
<ResponseField name="sample_rate" type="integer">`16000`</ResponseField>
<ResponseField name="encoding" type="string">`"pcm_s16le"`</ResponseField>

### transcript

<ResponseField name="text" type="string">The complete transcript so far, punctuated and cased. Replace what you display instead of appending.</ResponseField>
<ResponseField name="is_final" type="boolean">`true` when the current segment is settled.</ResponseField>
<ResponseField name="provider" type="string">`"a5sv2"`</ResponseField>

```json Example theme={null}
{"type": "transcript", "provider": "a5sv2", "text": "Good afternoon, everybody.", "is_final": true}
```

### session\_limit

The session reached 5 minutes or the account's usage limit. The final transcript and `finished` follow.

<ResponseField name="message" type="string">Why the session ended.</ResponseField>

### finished

<ResponseField name="audio_ms" type="integer">Audio received.</ResponseField>
<ResponseField name="billed_ms" type="integer">Audio counted toward usage.</ResponseField>
<ResponseField name="used_ms" type="integer">Account usage after this session.</ResponseField>
<ResponseField name="quota_ms" type="integer">The account's usage limit.</ResponseField>

### error

Sent just before the server closes the connection.

<ResponseField name="code" type="string">One of the codes below.</ResponseField>
<ResponseField name="message" type="string">Human-readable detail.</ResponseField>

| code | Close | Meaning |
| - | - | - |
| `invalid_start` | 4400 | The first message is missing or invalid |
| `unsupported_language` | 4400 | `language` is not English |
| `unknown_provider` | 4400 | `providers` names an unknown engine |
| `audio_before_ready` | 4400 | Audio sent before `ready` |
| `unauthorized` | 4401 | Missing or invalid API key |
| `model_access_denied` | 4403 | No access to A5S v2 Streaming ([talk to sales](https://research.aircaps.com/contact)) |
| `idle_timeout` | 4408 | No audio for 45 seconds |
| `quota_unavailable` | 4409 | Usage limit used up, or too many live sessions ([talk to sales](https://research.aircaps.com/contact)) |
| `realtime_rate_exceeded` | 4409 | Audio sent faster than real time |
| `a5sv2_unavailable` | 1013 | Temporarily unavailable; retry |
| `internal_error` | 1011 | Server error |

### pong

The reply to `ping`.

## Close codes

| Code | Meaning |
| - | - |
| 1000 | Normal close after `finished` |
| 1011 | Server error |
| 1013 | Temporarily unavailable; retry with backoff |
| 4400 | Invalid message or frame |
| 4401 | Authentication failed |
| 4403 | Forbidden: browser origin not allowed, or no access to the model |
| 4408 | Idle timeout |
| 4409 | Limit reached: usage, sessions, rate or frame size |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.