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

# Sessões em tempo real e WebSocket

> Transmita áudio e texto nos dois sentidos pelo AI Gateway via WebSocket, com modelos em tempo real ou com turnos sequenciais da Responses API.

O **AI Gateway** expõe dois endpoints WebSocket: um para modelos de fala e áudio em tempo real e outro que executa turnos da Responses API em uma única conexão. Ambos autenticam com a API key do workspace na solicitação de upgrade; um upgrade rejeitado retorna um status de erro HTTP.

## Sessões em tempo real

```
wss://router.toqan.ai/eu/v3/router/realtime?model=<provider>/<model>
```

Envie `Authorization: Bearer $TOQAN_API_KEY` na solicitação de upgrade. `model` é obrigatório: um valor ausente retorna `400`, um modelo desconhecido retorna `404` e um modelo sem protocolo em tempo real retorna `400`.

O endpoint roteia os modelos xAI Grok Voice: `xai/grok-voice-3.0` e `xai/grok-voice-latest`.

Uma sessão é contabilizada nos limites de taxa e nos orçamentos do workspace quando se conecta. Um limite esgotado rejeita o upgrade; consulte [Erros](#errors).

### OpenAI Realtime

O gateway faz proxy do protocolo de eventos do OpenAI Realtime: eventos JSON nos dois sentidos e frames binários para áudio. As restrições do Grok Voice, os formatos de áudio e o faturamento estão listados em [Modelos em tempo real](/docs/pt-BR/ai-gateway/supported-models.md#realtime-models).

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import WebSocket from "ws";

const socket = new WebSocket(
  "wss://router.toqan.ai/eu/v3/router/realtime?model=xai/grok-voice-3.0",
  "openai-beta.realtime-v1",
  { headers: { Authorization: `Bearer ${process.env.TOQAN_API_KEY}` } },
);

socket.on("open", () => {
  socket.send(JSON.stringify({
    type: "session.update",
    session: { voice: "eve", instructions: "Answer in one sentence." },
  }));
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
import json
import os

import websockets

async def main() -> None:
    async with websockets.connect(
        "wss://router.toqan.ai/eu/v3/router/realtime?model=xai/grok-voice-3.0",
        subprotocols=["openai-beta.realtime-v1"],
        additional_headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
    ) as socket:
        await socket.send(json.dumps({
            "type": "session.update",
            "session": {"voice": "eve", "instructions": "Answer in one sentence."},
        }))
        print(await socket.recv())


asyncio.run(main())
```

Uma recusa do upstream chega como um evento de erro no socket aberto, e não como um status HTTP, porque o upgrade já foi concluído.

## Responses via WebSocket

```
wss://router.toqan.ai/eu/v3/router/responses
```

Faça o upgrade com o subprotocolo `openai-beta.responses.v1` e `Authorization: Bearer $TOQAN_API_KEY`. Cada mensagem do cliente cria ou direciona uma resposta; o servidor transmite os mesmos eventos de uma solicitação HTTP com streaming.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "response.create",
  "stream_id": "turn-1",
  "response": {
    "model": "openai/gpt-5.6-sol",
    "input": "Explain quantum error correction in two sentences."
  }
}
```

* **Um turno por vez.** Envie o próximo `response.create` depois do evento final do turno anterior.
* **`stream_id`** identifica o turno e correlaciona os eventos que pertencem a ele.
* **`response.steer`** recebe um `previous_response_id` e um `input` e direciona o turno em andamento que produziu essa resposta. Uma falha chega como um evento `response.steer.failed` com um código como `response_not_found` ou `steering_not_supported`.
* **A duração da conexão** é de 30 minutos; o servidor envia um evento de erro `connection_duration_exceeded` e fecha o socket. Reconecte e continue com `previous_response_id`, que falha com `previous_response_not_found` quando a resposta já expirou.

## Erros

| Status | Significado |
| - | - |
| `400` | `model` está ausente no endpoint de tempo real, ou o modelo não tem protocolo em tempo real |
| `401` | O upgrade não traz uma API key válida |
| `404` | O modelo indicado não existe |
| `402` | Os créditos ou um orçamento do Grok Voice não cobrem a sessão |
| `429` | Um limite de taxa ou uma regra de orçamento rejeita a conexão |


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