Realtime WebSocket Integration

Realtime is used for low-latency voice, text, and tool calling interactions. It is not a regular HTTP streaming interface, nor is it /v1/chat/completions with stream: true. Clients need to establish a WebSocket connection.

Interface Information

Configuration	Value
WebSocket URL	wss://api.corerouter.cloud/v1/realtime?model=realtime-model-id
Protocol	WebSocket
Authentication	Authorization: Bearer sk-... or Sec-WebSocket-Protocol
Model Requirement	Model ID from console that supports Realtime
Common Events	session.update, conversation.item.create, response.create, input_audio_buffer.append

Realtime must include model in the URL query parameters. For example:

wss://api.corerouter.cloud/v1/realtime?model=realtime-model-id

Server-Side Connection Method

If your program runs on the server, use the Authorization Header first. This way the API Key won't be exposed to browser users.

import WebSocket from "ws";

const apiKey = process.env.COREROUTER_API_KEY;
const url = "wss://api.corerouter.cloud/v1/realtime?model=realtime-model-id";

const ws = new WebSocket(url, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

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

  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [
        { type: "input_text", text: "Hello, please introduce CoreRouter in one sentence." }
      ],
    },
  }));

  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.on("message", (data) => {
  console.log(data.toString());
});

Install dependency:

npm install ws

Browser or Official Realtime SDK Style Connection

Browser WebSocket cannot customize Authorization Header. Some Realtime SDKs put the API Key in the Sec-WebSocket-Protocol subprotocol:

realtime, openai-insecure-api-key.sk-xxxxxxxxxxxxxxxx

If you must connect this way, note:

• API Key will appear in the browser runtime environment; not suitable for direct production use.
• Recommended: issue short-term sessions from your own server or reverse proxy Realtime requests.
• Only use long-term API Keys in trusted environments or local testing.

Minimal Event Flow

Common text session flow:

1. Establish WebSocket connection.
2. Send session.update to set model behavior, input/output types, voice, and tools.
3. Send conversation.item.create to write user message.
4. Send response.create to trigger model response.
5. Continuously receive server events, such as text deltas, audio deltas, tool calls, or response.done.

Audio Input

Audio is typically sent via input_audio_buffer.append with Base64-encoded audio chunks. Audio format must match input_audio_format in session.update.

{
  "type": "input_audio_buffer.append",
  "audio": "base64-audio-chunk"
}

Different Realtime models support different sample rates, encodings, voices, and transcription capabilities. Refer to console model descriptions.

Common Issues

• 401 on connection: Check if API Key is complete; if using Sec-WebSocket-Protocol, confirm it includes openai-insecure-api-key.sk-....
• 404 or model not found on connection: Confirm URL includes model=realtime-model-id from console Realtime models.
• Can connect but no response: Confirm response.create was sent and check if session.update set available modalities.
• Browser connection fails: Check CORS, whether proxy supports WebSocket, and whether server proxy protects API Key.
• Regular chat models unavailable: Realtime requires dedicated Realtime models or channels; cannot directly reuse regular chat models.