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

# Modellix Live Overview

> Real-time, bidirectional voice and vision sessions over WebSocket. Connect to Gemini Live through Modellix with one API key, send audio, video frames, and text, and pay per completed turn.

Modellix Live is a WebSocket passthrough for real-time models such as Gemini Live. Open one connection, stream audio, video frames, and text in, and receive spoken or text replies as they are generated. Authentication, balance checks, and billing are handled by Modellix; the message format is the same as the upstream Live API.

<Note>
  Live is a long-lived WebSocket session. It does not use the async task flow of
  Media Models (`https://api.modellix.ai` task polling) or the HTTP request and
  response model of LLM (`https://llm.modellix.ai`).
</Note>

## What You Get

<Columns cols={2}>
  <Card title="Native Live protocol" icon="plug">
    Frames are forwarded verbatim in both directions. Only `setup.model` is
    rewritten by the gateway, so official Live client code works with a URL and
    key change.
  </Card>

  <Card title="One API key" icon="key">
    Authenticate with `Authorization: Bearer` using a Modellix key from the
    [console](https://modellix.ai/console/api-key)—not a vendor credential.
  </Card>

  <Card title="Per-turn billing" icon="receipt">
    Each completed turn is billed from the upstream token usage, split by input
    and output modality.
  </Card>

  <Card title="Multimodal input" icon="layers">
    Send text, 16 kHz PCM audio, and JPEG video frames in one session.
  </Card>
</Columns>

## Base URL and Auth

| Item | Value |
| - | - |
| Endpoint | `wss://api.modellix.ai/api/v1/live/{provider}/{model_id}` |
| Example | `wss://api.modellix.ai/api/v1/live/google/gemini-3.8-live` |
| Auth | `Authorization: Bearer <Modellix API Key>` on the WebSocket handshake |

```http theme={null}
Authorization: Bearer mdlx-xxxxxxxx
```

<Warning>
  Only the `Authorization` header is accepted. Do not pass the key in the URL
  query string.
</Warning>

Browsers cannot set custom headers on a WebSocket handshake. Connect from your backend, or from a client runtime that supports request headers.

## Supported Models

| Model ID | Input | Output | Context | Parameters |
| - | - | - | - | - |
| `google/gemini-3.8-live` | Text, audio, video frames | Audio (plus text transcription) | 131,072 input tokens, 65,536 output tokens | [Gemini 3.8 Live](https://docs.modellix.ai/live/models/gemini-3-8-live) |

Each model has its own page with a quick start, request parameters, returned messages, formats, limits, and examples.

## Session Flow

<Steps>
  <Step title="Open the Connection">
    Connect with the `Authorization` header. If the handshake fails, you get an
    HTTP status instead of a WebSocket (see [Handshake Errors](#handshake-errors)).
  </Step>

  <Step title="Send Setup">
    The first frame must be a `setup` message and must arrive within 30 seconds.
    Configure response modalities, voice, system instruction, transcription, and
    session options here. Wait for `setupComplete`.
  </Step>

  <Step title="Stream Input">
    Send `realtimeInput` messages with `text`, `audio`, or `video`. Replies stream
    back as `serverContent` frames.
  </Step>

  <Step title="Turn Complete">
    When the model finishes, `serverContent.turnComplete` arrives together with
    `usageMetadata`. That turn is billed.
  </Step>

  <Step title="Close">
    Close the WebSocket normally (code `1000`) when you are done.
  </Step>
</Steps>

## Billing

* **Per turn.** Each `turnComplete` produces one billing record. The record is based on the token `usage` reported for that turn.
* **By modality.** Input text, image, video, and audio, and output text, audio, and video, are priced separately. Thinking tokens are billed at the output text rate. Unit prices and invoices follow the console.
* **Context is billed again each turn.** The upstream model includes the accumulated conversation in each turn, so later turns in a long session cost more. Use context window compression for long sessions; see [Sessions and Limits](https://docs.modellix.ai/live/models/gemini-3-8-live#sessions-and-limits).
* **Incomplete turns.** If a connection ends in the middle of a turn, the usage received so far is billed.
* **Balance.** The session starts only with sufficient balance. If the balance runs out mid-session, the connection is closed with code `4402` after the current turn at the latest.

## Errors

### Handshake Errors

Failures before the WebSocket upgrade return an HTTP status with the same JSON error body as the Media API:

```json theme={null}
{
  "code": 401,
  "message": "Authentication failed: invalid API key"
}
```

* `code` (integer) equals the HTTP status code.
* `message` (string) is formatted as `"<Category>: <detail>"`.

| HTTP | Description | Retryable |
| - | - | - |
| `400` | Not a WebSocket upgrade request, or invalid parameters | No. Fix the request. |
| `401` | Missing, malformed, or invalid API key | No. Provide a valid key. |
| `402` | Insufficient balance | No. Recharge your account. |
| `404` | Model does not exist or does not support Live | No. Check the model ID. |
| `429` | Rate limit or concurrent session limit reached | Yes. Back off, or close another session. |
| `500` | Internal gateway error | Yes. Retry with backoff. |
| `503` | Service is restarting or at capacity. May include `Retry-After`. | Yes. Retry after the delay. |

### Close Codes

After the connection is open, the server ends a session with a WebSocket close code and a short reason.

| Code | Reason | Meaning | Reconnect |
| - | - | - | - |
| `1000` | | Normal closure | |
| `1001` | `service is restarting` | The service is shutting down. | Yes |
| `1001` | `ping timeout` | The server did not receive a pong in time. | Yes |
| `1008` | `timed out waiting for setup message` | `setup` was not sent within 30 seconds. | After fixing |
| `1008` | `client send rate exceeded` | Upload rate per connection exceeded. | After slowing down |
| `1008` | Other text | The first frame was not a valid `setup`. | After fixing |
| `1009` | `frame too large` | A message exceeded the maximum size (currently 16 MiB). | After fixing |
| `1011` | `upstream unavailable` | The upstream model is unavailable, or an internal error occurred. | Yes |
| `4402` | `insufficient balance` | Balance exhausted during the session. | After recharging |
| `4408` | `max connection duration reached` | Maximum connection duration reached. | Yes, use session resumption |

Close codes sent by the upstream model are passed through to you.

### Keepalive

The server sends a WebSocket ping every 30 seconds and closes a connection that stops answering. Standard WebSocket libraries reply with a pong automatically. Do not disable it, and keep your event loop responsive while playing audio.

## Limits

* Messages larger than 16 MiB are rejected with `1009`.
* Upload rate is limited per connection. Send video at 1 frame per second and audio in real time to stay far below the limit; exceeding it closes the connection with `1008`.
* Concurrent sessions are limited per team. Exceeding the limit returns `429` on the handshake.
* A session that is idle still counts toward the concurrent limit. Close connections you no longer use.

## Next Steps

<Columns cols={2}>
  <Card title="Gemini 3.8 Live" icon="radio" href="https://docs.modellix.ai/live/models/gemini-3-8-live">
    Quick start, request parameters, returned messages, and examples.
  </Card>

  <Card title="Get an API Key" icon="key" href="https://modellix.ai/console/api-key">
    Create a Modellix API key in the console.
  </Card>
</Columns>


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