Realtime API

GET /v1/realtime opens a low-latency, bidirectional WebSocket session. It is suitable for live audio and event-stream applications, but available models, modalities, and event types depend on the selected channel.

Connection URL

wss://api.nbility.ai/v1/realtime?model=YOUR_REALTIME_MODEL

Use GET /v1/models or the console to choose a model that explicitly supports Realtime.

Browser JavaScript

The browser WebSocket constructor cannot set an Authorization header. Pass the key through the subprotocol values:

const apiKey = 'YOUR_API_KEY';
const model = 'YOUR_REALTIME_MODEL';

const ws = new WebSocket(
  `wss://api.nbility.ai/v1/realtime?model=${encodeURIComponent(model)}`,
  [
    'realtime',
    `openai-insecure-api-key.${apiKey}`,
    'openai-beta.realtime-v1',
  ],
);

ws.addEventListener('open', () => {
  console.log('Realtime connected');
});

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  console.log(message);
});

ws.addEventListener('error', (event) => {
  console.error('Realtime connection failed', event);
});

Do not use an ?access_token= query parameter: Nbility's Realtime authentication does not read the key from it.

Server-side clients

If the WebSocket library supports custom request headers, you can instead send:

Authorization: Bearer YOUR_API_KEY

The exact option depends on the language and library.

Events and lifecycle

After the handshake, client and server exchange JSON events for session configuration, input, generation requests, incremental output, and errors. Supported events and fields can vary by upstream model, so clients should:

• Ignore unknown event types and retain raw events for troubleshooting.
• Define explicit heartbeat, timeout, disconnect, and reconnect behavior.
• Never ship a long-lived API key in frontend code; in production, proxy the connection or issue short-lived access from your backend.
• Re-create session state after reconnecting instead of assuming the old connection survives.

For a 401 handshake, check the subprotocol order and key. For 404 or model errors, verify that the selected model supports Realtime.