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

# WebSocket API

> Real-time speech-to-speech translation over a single persistent WebSocket connection

The Stream API provides real-time speech-to-speech translation over a single persistent WebSocket connection. It supports both **consecutive mode** (speak, wait, hear translation) and **simultaneous mode** (continuous translation as you speak).

This page covers the WebSocket transport: endpoint, authentication, audio frames, connection errors, and connection lifetime. For the shared application message layer, including `init`, `configure`, `flush`, and server events, see the [Stream message layer](/Docs/Language-Translation/Stream-Message-Layer).

## Endpoint

```
WebSocket: wss://api.sanaslt.com/v3/stream
```

## Authentication

Authentication is provided via query parameters. Provide **one** of the following:

| Parameter | Description                      |
| --------- | -------------------------------- |
| `token`   | JWT Bearer token (from Supabase) |
| `api_key` | API key                          |

Example connection URLs:

```
wss://api.sanaslt.com/v3/stream?token=<jwt_token>
wss://api.sanaslt.com/v3/stream?api_key=<api_key>
```

Authentication is validated **before** the WebSocket upgrade. On failure the server returns HTTP 401, not a WebSocket close frame.

## Transport Model

* Send Stream JSON messages as WebSocket text frames.
* Send input audio as raw PCM bytes in WebSocket binary frames after receiving `configured`.
* Receive output audio as raw PCM bytes in WebSocket binary frames.
* Do not wrap audio in JSON or base64.

For message schemas, usage modes, and examples, see the [Stream message layer](/Docs/Language-Translation/Stream-Message-Layer).

## Connection Lifecycle

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Client
    participant Server

    Client->>Server: WebSocket connect with auth
    Client->>Server: Send init text frame
    Client->>Server: Send configure text frame
    Server-->>Client: Send configured text frame
    Client->>Server: Stream input audio as binary frames
    Server-->>Client: Send Stream events as text frames
    Server-->>Client: Stream output audio as binary frames
    opt Manual turn finalization
        Client->>Server: Send flush text frame
    end
    opt End session
        Client->>Server: Close WebSocket
    end
```

## Audio Frames

Input audio and output audio use raw PCM binary frames on the WebSocket transport.

* Encoding: 16-bit signed integer PCM (little-endian)
* Channels: Mono (1 channel)
* Input sample rate: Must match `input_sample_rate` from `init`
* Output sample rate: Matches `output_sample_rate` from `init`

Send audio in small frames, typically 10-20 ms of audio per frame, for the lowest latency. Larger frames add latency equal to the frame duration.

## Error Handling

### Connection Errors

If authentication fails, the server returns an HTTP error before the WebSocket upgrade:

| HTTP Status | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| 401         | Missing, empty, invalid, or expired authentication credentials |

### Runtime Errors

During a session, runtime errors are delivered as `error` messages. Non-fatal errors, such as bad JSON or an unknown message type, do not close the connection. Fatal backend errors may be followed by the connection closing.

See [`error`](/Docs/Language-Translation/Stream-Message-Layer#error) for the message shape.

### Inactivity Timeout

If no messages are sent or received for 60 seconds (configurable), the server closes the WebSocket connection.

## Migration

For the v2 consecutive API to v3 Stream API migration guide, see [Migration Guide: v2 Consecutive API to v3 Stream API](/Docs/Language-Translation/Stream-Message-Layer#migration-guide-v2-consecutive-api-to-v3-stream-api).