> ## 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.

# Live streaming

> Real-time captions with A5S v2 Streaming over WebSocket.

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

## Protocol

<Steps>
  <Step title="Connect">
    Open the WebSocket with your key in the handshake header: `Authorization: Bearer aircaps_sk_...`
  </Step>

  <Step title="Send start">
    The first message is JSON. `language` accepts `en` and regional variants such as `en-US`; multilingual support is planned.

    ```json theme={null}
    {
      "type": "start",
      "providers": ["a5sv2"],
      "encoding": "pcm_s16le",
      "sample_rate": 16000,
      "channels": 1,
      "language": "en-US"
    }
    ```
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Finish">
    Send `{"type": "finish"}`. The server sends the final transcript, then a `finished` message, and closes.
  </Step>
</Steps>

## Messages from the server

```json theme={null}
{"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:

```json theme={null}
{
  "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](https://research.aircaps.com/contact) to raise limits) |
| 1013 | Temporarily unavailable; retry |
| 1011 | Server error |

See the [Python sample](/guides/samples#stream-a-wav-file).


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