Connect Live Session
GETwss://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
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | String | Conditional | Bearer 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-key | String | No | Anthropic-style alternative to Authorization. |
| Upgrade | String | Yes | Must 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
| Status | When |
|---|---|
400 | Request is not a WebSocket upgrade, or the handshake is invalid. |
401 | Missing or invalid Knox API key (or expired ek_knox_…). |
402 | Account balance is not greater than $0.01. |
403 | The token's model allow-list does not include gpt-live-1. |
502 | No 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).