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

# Realtime API

> Use the OpenAI Realtime-compatible WebSocket route for real-time interactions.

# Realtime API

The Realtime route uses a WebSocket connection and is suitable for low-latency voice conversations, real-time event streams, and bidirectional interaction scenarios. This route goes through TokenAuth, model rate limiting, and channel distribution.

## Connection URL

```text theme={null}
wss://https://octopusx.ai/v1/realtime
```

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

If the client cannot conveniently set WebSocket request headers, you can use a supported temporary token or have the proxy layer inject the authentication header according to your gateway configuration.

## Connection Example

```js theme={null}
const ws = new WebSocket("wss://https://octopusx.ai/v1/realtime", [], {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      modalities: ["text"],
      instructions: "You are a real-time voice assistant."
    }
  }));
};

ws.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};
```

## Common Events

| event                      | Description                  |
| -------------------------- | ---------------------------- |
| `session.update`           | Update session configuration |
| `conversation.item.create` | Create a conversation item   |
| `response.create`          | Trigger a model response     |
| `response.text.delta`      | Text delta                   |
| `response.done`            | Response complete            |

## Related APIs

* [Chat Completions API (default streaming)](./chat-completions-stream)
* [OpenAI Multimodal Responses API](./openai-responses)