Sessões em tempo real e WebSocket

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.

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.

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." },
  }));
});

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.

{
  "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

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores