Skip to main content

Connect Live Session

GET 

wss://api.knox.chat/v1/live/sessions

Open a billed full-duplex GPT-Live conversation. Knox authenticates your API key, selects an upstream OpenAI Live channel, and relays the event stream.

This is not POST /v1/chat/completions and not GET /v1/realtime. Clients must upgrade to WebSocket. A plain HTTP GET returns 400. The same route is mounted under /api/v1.

Accepted model ID: gpt-live-1 only. Put it in session.start. Do not pass ?model= (Knox rejects non-Live ids if present). For session config, billing, delegation, WebRTC, and SIP, see the GPT-Live guide.

Official OpenAI references: GPT-Live overview, Connect, WebSockets.

Request​

Request Headers​

NameTypeRequiredDescription
AuthorizationStringConditionalBearer sk-… or Bearer ek_knox_…. Required unless the key is sent as a WebSocket subprotocol or (WebSocket upgrades only) as ?api_key= / ?authorization=.
x-api-keyStringNoAnthropic-style alternative to Authorization.
UpgradeStringYesMust be websocket.

Browser native WebSocket cannot set HTTP headers. Use the subprotocol form:

const ws = new WebSocket(
"wss://api.knox.chat/v1/live/sessions",
["openai-insecure-api-key.sk-YOUR_KNOX_KEY"]
);

Knox hashes the Knox user id and sends OpenAI-Safety-Identifier upstream; you do not set this yourself.

First message​

The first JSON text frame must be session.start (timeout 30 seconds). Wait for session.started before sending audio.

{
"type": "session.start",
"event_id": "event_start",
"session": {
"model": "gpt-live-1",
"instructions": "Be concise. Delegate current-facts questions to the backend.",
"audio": {
"format": { "type": "audio/pcm", "rate": 24000 },
"output": { "voice": "marin" }
},
"delegation": {
"type": "responses",
"responses": {
"model": "gpt-6-luna",
"tools": [{ "type": "web_search" }],
"tool_choice": "auto"
}
}
}
}

Knox pins session.model to gpt-live-1, drops unknown keys (including type), and leaves omitted instructions / delegation unset so OpenAI applies its defaults (client-mode delegation). Extra fields cause unknown_parameter upstream if they were forwarded.

Connection example​

import WebSocket from "ws";

const ws = new WebSocket("wss://api.knox.chat/v1/live/sessions", {
headers: { Authorization: "Bearer " + process.env.KNOX_API_KEY },
});

ws.on("open", () => {
ws.send(JSON.stringify({
type: "session.start",
session: {
model: "gpt-live-1",
audio: { format: { type: "audio/pcm", rate: 24000 } },
},
}));
});

ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "session.started") {
ws.send(JSON.stringify({
type: "session.input_audio.append",
audio: "<base64 pcm16>",
}));
}
});

After session.started, send session.input_audio.append with base64 PCM16 mono 24 kHz (or the format you configured). Play session.output_audio.delta. End with session.close and wait for session.closed.

Error Responses​

StatusWhen
400Request is not a WebSocket upgrade, or the handshake is invalid.
401Missing or invalid Knox API key (or expired ek_knox_…).
402Account balance is not greater than $0.01.
403The token's model allow-list does not include gpt-live-1.
502No OpenAI-compatible Live channel is available, or the upstream connect failed.

After a successful upgrade, failures can also arrive as WebSocket error events (session_start_required, invalid_session, invalid_json).