Two Ways to Call gpt-live-1: the OpenAI Live API and Codex Live V3
Posted November 19, 2026 by XAI Technical Teamย โย 12ย min read

gpt-live-1 is OpenAI's full-duplex voice model: it listens and speaks at the same time, users can interrupt at any moment, and it hands reasoning or tool calls to a backend model when needed. On XAI Router there are two ways to call it:
- The official OpenAI Live API: identical to the OpenAI documentation; only the address and the key change.
- Codex Live V3: the voice protocol used by the Codex client. Its request format, headers and events differ from the official API.
Which one you use is decided by the plan you buy. Each plan is tied to a different upstream line in the backend, and the request bodies and events of the two methods cannot be mixed. Please read section 1 before you order.
1. Check your plan first
| Your plan | Method to use | Suitable clients |
|---|---|---|
| A plan whose upstream is the official OpenAI API | OpenAI Live API | Apps built on the OpenAI docs or SDK, voice customer service, telephone gateways |
| A Codex plan | Codex Live V3 | The Codex client and third-party clients that support the Codex Live protocol |
If you are not sure which line your plan uses, check the plan description in the console or ask support before integrating. Using the wrong method returns a clear error; see section 5.
2. The two methods side by side
| OpenAI Live API | Codex Live V3 | |
|---|---|---|
| Model | gpt-live-1 | gpt-live-1 |
| WebSocket | wss://api.xairouter.com/v1/live/sessions, first frame session.start | Creating a session over WebSocket is not supported |
| WebRTC session creation | POST https://api.xairouter.com/v1/live/sessions, JSON: session + transport | POST https://api.xairouter.com/v1/live, multipart form: sdp + session |
| Success response | HTTP 201, JSON with session.id and transport.sdp | HTTP 201, the body is the answer SDP and Location carries the call_id |
| Attach to the session (sideband) | wss://api.xairouter.com/v1/live/sessions/{id}/attach | wss://api.xairouter.com/v1/live/{call_id} |
| Authentication | Authorization: Bearer <API key> | Authorization: Bearer <API key> |
| Protocol header | None | openai-alpha: quicksilver=v2 (required) |
session.type | Not needed | Do not set it |
| Main events | session.started, session.input_transcript.delta, session.output_transcript.delta, session.output_audio.delta, session.closed | session.started, input_transcript.added, output_transcript.added, turn.done |
| Details | Section 3; OpenAI Live guide | Section 4 |
Rules for both methods:
- Keep the API key on your server. Never put it in a browser or an app. Browsers use WebRTC, with your backend creating the session.
/v1/chat/completionsand ordinary/v1/responsesrequests never become Live voice. Adding a chat model with the same name to a client does not give it voice either.- HTTP
201only means the session was created. Full success means the session starts, the user's speech is transcribed, and you can hear the model's reply.
3. Method 1: the OpenAI Live API
For plans whose upstream is the official OpenAI API. Endpoints, request bodies and events match the OpenAI documentation.
Session configuration
| Field | Description |
|---|---|
model | Required, gpt-live-1; cannot be changed after start |
instructions | Conversation instructions |
audio.output.voice | Voice, default marin |
audio.format | WebSocket only, for example {"type": "audio/pcm", "rate": 24000}; WebRTC negotiates it in SDP, so do not set it |
delegation | Optional, client or responses, hands reasoning and tool calls to a backend |
WebSocket audio is Base64-encoded PCM: 24 kHz mono 16-bit little-endian by default, without a WAV header. 16 kHz PCM and 8 kHz G.711 ฮผ-law (audio/pcmu) and A-law (audio/pcma) are also supported.
WebSocket example (Python)
Good for servers, telephone gateways and testing. Use Python 3.9 or later and install the dependency:
pip install websocketsThe script reads a 24 kHz, mono, 16-bit WAV file as the user's speech, prints both transcripts, and saves the model's spoken reply as reply.wav:
import asyncio, base64, json, os, wave
import websockets
URL = "wss://api.xairouter.com/v1/live/sessions"
KEY = os.environ["XAI_API_KEY"]
CHUNK = 4800 # 0.1 s at 24 kHz / 16-bit
async def main(path="question_24k.wav"):
pcm = wave.open(path).readframes(10**9)
reply, heard, said = bytearray(), [], []
started = asyncio.Event()
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.start",
"session": {
"model": "gpt-live-1",
"instructions": "You are a concise, friendly voice assistant. Answer in one sentence.",
"audio": {
"format": {"type": "audio/pcm", "rate": 24000},
"output": {"voice": "marin"},
},
},
}))
async def reader():
async for raw in ws:
event = json.loads(raw)
kind = event["type"]
if kind == "session.started":
started.set()
elif kind == "session.output_audio.delta":
reply.extend(base64.b64decode(event["delta"]))
elif kind == "session.input_transcript.delta":
heard.append(event["delta"])
elif kind == "session.output_transcript.delta":
said.append(event["delta"])
elif kind == "error":
print("error:", raw)
elif kind == "session.closed":
print("session closed:", event.get("reason"))
return
task = asyncio.create_task(reader())
await asyncio.wait_for(started.wait(), 15)
silence = b"\x00" * CHUNK
chunks = [pcm[i:i + CHUNK] for i in range(0, len(pcm), CHUNK)]
# Stream at real-time pace: the question, then 8 s of silence for the answer
for chunk in chunks + [silence] * 80:
await ws.send(json.dumps({
"type": "session.input_audio.append",
"audio": base64.b64encode(chunk).decode(),
}))
await asyncio.sleep(0.1)
await ws.send(json.dumps({"type": "session.close"}))
await asyncio.wait_for(task, 15)
print("user:", "".join(heard))
print("assistant:", "".join(said))
with wave.open("reply.wav", "wb") as out:
out.setnchannels(1)
out.setsampwidth(2)
out.setframerate(24000)
out.writeframes(bytes(reply))
asyncio.run(main())Run it:
XAI_API_KEY=your_api_key python3 live_ws.pyKey points:
- The first message after connecting must be
session.start. Send audio only aftersession.startedarrives. - Stream audio at roughly real-time pace. A full-duplex model listens over time, so pushing a whole recording at once gives unpredictable results.
- To finish, send
session.closeand wait forsession.closedbefore disconnecting, so you receive the final usage.
WebRTC example (browser + Node.js backend)
For web pages and apps. The browser creates an SDP offer and passes it to your backend; the backend calls POST /v1/live/sessions with the key and returns the answer SDP to the browser. Audio flows over WebRTC media tracks and events over the oai-events data channel.
Backend server.mjs (Node.js 22+, npm install express@5):
import express from "express";
const app = express();
app.use(express.text({ type: "application/sdp", limit: "1mb" }));
app.use(express.static("public"));
app.post("/session", async (req, res) => {
// In production, check the user's login, rate limits and Origin here
const upstream = await fetch("https://api.xairouter.com/v1/live/sessions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
session: {
model: "gpt-live-1",
instructions: "You are a concise, friendly voice assistant.",
audio: { output: { voice: "marin" } },
},
transport: { type: "webrtc", sdp: req.body },
}),
});
const data = await upstream.json();
if (!upstream.ok) return res.status(upstream.status).json(data);
res.json({ sessionId: data.session.id, sdp: data.transport.sdp });
});
app.listen(3000, "127.0.0.1", () => console.log("Open http://localhost:3000"));Script for public/index.html (needs HTTPS or localhost and a user click):
async function startCall() {
const pc = new RTCPeerConnection();
const player = new Audio();
player.autoplay = true;
pc.ontrack = (event) => { player.srcObject = event.streams[0]; };
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
mic.getTracks().forEach((track) => pc.addTrack(track, mic));
// Create the data channel before createOffer
const events = pc.createDataChannel("oai-events");
events.onmessage = ({ data }) => {
const event = JSON.parse(data);
if (event.type === "session.input_transcript.delta") console.log("me:", event.delta);
if (event.type === "session.output_transcript.delta") console.log("assistant:", event.delta);
if (event.type === "session.closed") {
pc.close();
mic.getTracks().forEach((track) => track.stop());
}
};
await pc.setLocalDescription(await pc.createOffer());
await new Promise((resolve) => {
if (pc.iceGatheringState === "complete") return resolve();
pc.addEventListener("icegatheringstatechange", () => {
if (pc.iceGatheringState === "complete") resolve();
});
setTimeout(resolve, 3000);
});
const response = await fetch("/session", {
method: "POST",
headers: { "Content-Type": "application/sdp" },
body: pc.localDescription.sdp,
});
const { sdp } = await response.json();
await pc.setRemoteDescription({ type: "answer", sdp });
// Hang up: send session.close, then release the connection and microphone on session.closed
return () => events.send(JSON.stringify({ type: "session.close" }));
}With WebRTC, do not send session.start or session.input_audio.append on the data channel: the HTTP request itself starts the session, and all audio goes over the media tracks.
Verification on this site
On November 20, 2026 we verified both WebSocket and WebRTC through api.xairouter.com with a synthesized English question:
| WebSocket | WebRTC | |
|---|---|---|
| Session | session.started received | HTTP 201, WebRTC connected, session.started on the data channel |
| User transcript | Question recognized correctly | Question recognized correctly |
| Model reply | Transcript and audio output normal | Transcript and remote audio track normal |
| End | session.closed, reason close_requested | Same |
The WebSocket check used the Python script above; the WebRTC check used a Python aiortc client, and the Node.js and browser code above follow the same flow, so please verify it in your own browser before deploying. Delegation, Chinese speech and interruptions were outside this check.
4. Method 2: Codex Live V3
For Codex plans. It uses the Live V3 protocol of the Codex client and supports only a WebRTC session plus a sideband WebSocket attached to the same session. This line was verified on September 11, 2026 with real voice input, user transcription, a model reply and received audio; that does not mean every third-party client has been tested.
Client requirements
Filling in an API address, key and model name is not enough for an ordinary chat client to support this protocol:
| Client capability | Usable with this method? |
|---|---|
| Custom Live address, WebRTC SDP, a sideband on the same call_id, and Live V3 events | Yes, as long as the key can access the model |
| Only Base URL, API key and chat model settings | The client needs Live voice protocol support |
| Only creating new voice sessions directly over WebSocket | No; the Codex line supports WebRTC plus sideband only |
| Only the official OpenAI Live API or the Realtime protocol | Request bodies and events cannot be mixed; for the official protocol, choose the plan for method 1 |
| Only speech-to-text or text-to-speech | These are separate ASR/TTS APIs, not Live conversation |
Parameters
| Parameter | Value |
|---|---|
| Create a session | POST https://api.xairouter.com/v1/live, multipart form: sdp + session |
| Sideband for the same session | wss://api.xairouter.com/v1/live/{call_id} |
| Authentication header | Authorization: Bearer <your API key> |
| Protocol header | openai-alpha: quicksilver=v2 (for both session creation and the sideband) |
| Model | Set session.model to gpt-live-1 explicitly |
session.type | Do not set it |
| Example voice | cove |
If your client appends /v1/live by itself, enter the API root https://api.xairouter.com to avoid /v1/v1/live. The call_id must come from the session you just created; never type it by hand or reuse an old one.
Flow
- The browser or native client gets the microphone and creates a WebRTC offer SDP with an audio track and an
oai-eventsdata channel. - Your backend sends
sdpandsessionas a multipart form to/v1/live, with the key and the protocol header. - Success is HTTP
201; the body is the answer SDP andLocationcontains the new session'scall_id. - Your backend opens the sideband at
/v1/live/{call_id}and waits forsession.started; the browser applies the answer SDP to complete the WebRTC connection. - Audio goes over WebRTC; transcripts and turns arrive as
input_transcript.added,output_transcript.added,turn.doneand similar events. To finish, sendsession.close, close the connection and stop the microphone.
The browser's native WebSocket cannot set an Authorization header, so the sideband should be opened by your backend, and the long-lived key stays on the backend.
Quick command-line check (offer.sdp must be a real WebRTC offer generated by a client):
curl -X POST https://api.xairouter.com/v1/live \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "openai-alpha: quicksilver=v2" \
-F "sdp=<offer.sdp;type=application/sdp" \
-F 'session={"model":"gpt-live-1","instructions":"Answer briefly.","audio":{"output":{"voice":"cove"}},"delegation":{"type":"client"}};type=application/json'Try it locally: browser microphone + Node backend
A minimal third-party voice client, useful for checking your account and the protocol first. Install Node.js 22 or later and create a directory:
mkdir live-voice-demo
cd live-voice-demo
npm init -y
npm install express@5 ws@8Create .env in that directory with the API address and your own key; add .env to .gitignore and never put it in frontend code:
ROUTER_API_BASE=https://api.xairouter.com
ROUTER_API_KEY=your_api_key1. Create the backend server.mjs
The backend submits the SDP, keeps session.model, opens the sideband for the same session, and reports success only after session.started. Each session in the example lasts at most 3 minutes so it cleans itself up; this is an example setting, not a platform limit.
import express from "express";
import WebSocket from "ws";
import { randomUUID } from "node:crypto";
import { fileURLToPath } from "node:url";
const api = new URL(process.env.ROUTER_API_BASE);
const key = process.env.ROUTER_API_KEY;
if (!key) throw new Error("Set ROUTER_API_KEY in .env");
const headers = {
Authorization: `Bearer ${key}`,
"openai-alpha": "quicksilver=v2",
};
const app = express();
const sessions = new Map();
app.use(express.text({ type: "application/sdp", limit: "1mb" }));
app.get("/", (_req, res) => {
res.sendFile(fileURLToPath(new URL("./index.html", import.meta.url)));
});
function closeSocket(ws) {
if (!ws) return;
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: "session.close" }));
ws.close();
} else if (ws.readyState !== WebSocket.CLOSED) {
ws.terminate();
}
}
app.post("/session", async (req, res) => {
if (typeof req.body !== "string" || !req.body.startsWith("v=0")) {
return res.status(400).json({ error: "A real WebRTC offer SDP is required" });
}
let ws;
try {
const form = new FormData();
form.set("sdp", new Blob([req.body], { type: "application/sdp" }));
form.set("session", new Blob([JSON.stringify({
model: "gpt-live-1",
instructions: "Answer the user directly and briefly. Do not delegate to tools.",
audio: { output: { voice: "cove" } },
delegation: { type: "client" },
})], { type: "application/json" }));
const upstream = await fetch(new URL("/v1/live", api), {
method: "POST", headers, body: form,
signal: AbortSignal.timeout(30000), redirect: "error",
});
const sdp = await upstream.text();
if (upstream.status !== 201 || !sdp.startsWith("v=0")) {
throw new Error(`Create failed: HTTP ${upstream.status} ${sdp.slice(0, 300)}`);
}
const location = upstream.headers.get("location");
if (!location) throw new Error("The create response has no Location");
const callId = new URL(location, api).pathname.split("/").filter(Boolean).at(-1);
if (!callId) throw new Error("Location has no call_id");
// Take only the call_id; always send the key to the configured API domain.
const sideband = new URL(`/v1/live/${encodeURIComponent(callId)}`, api);
sideband.protocol = api.protocol === "https:" ? "wss:" : "ws:";
ws = new WebSocket(sideband, { headers, handshakeTimeout: 15000 });
let timer;
try {
await new Promise((resolve, reject) => {
timer = setTimeout(() => reject(new Error("Timed out waiting for session.started")), 15000);
ws.on("error", reject);
ws.on("close", () => reject(new Error("The sideband closed")));
ws.on("message", raw => {
let event;
try { event = JSON.parse(raw.toString()); } catch { return; }
if (event.type === "session.started") resolve();
if (event.type === "error") {
reject(new Error(event.error?.message || "Live session error"));
}
});
});
} finally {
clearTimeout(timer);
}
console.log("sideband: session.started");
const id = randomUUID();
const expiry = setTimeout(() => closeSocket(ws), 3 * 60 * 1000);
sessions.set(id, ws);
ws.once("close", () => {
clearTimeout(expiry);
sessions.delete(id);
});
res.json({ id, sdp });
} catch (error) {
closeSocket(ws);
res.status(502).json({ error: error.message });
}
});
app.delete("/session/:id", (req, res) => {
closeSocket(sessions.get(req.params.id));
sessions.delete(req.params.id);
res.sendStatus(204);
});
app.listen(3000, "127.0.0.1", () => console.log("Open http://localhost:3000"));2. Create the page index.html
The page exchanges SDP with the backend through the same-origin /session; WebRTC carries the microphone and the reply audio, and captions come from the Live V3 turn.done event.
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Live voice demo</title>
<button id="start">Start voice</button>
<button id="stop" disabled>Stop voice</button>
<audio id="audio" autoplay controls></audio>
<pre id="log" aria-live="polite"></pre>
<script type="module">
const startButton = document.querySelector("#start");
const stopButton = document.querySelector("#stop");
const audio = document.querySelector("#audio");
const output = document.querySelector("#log");
const log = text => { output.textContent += `${text}\n`; };
let pc, mic, sessionId;
async function stop() {
mic?.getTracks().forEach(track => track.stop());
pc?.close();
audio.srcObject = null;
const id = sessionId;
pc = mic = sessionId = undefined;
startButton.disabled = false;
stopButton.disabled = true;
if (id) {
await fetch(`/session/${encodeURIComponent(id)}`, {
method: "DELETE", keepalive: true,
}).catch(() => log("Close request failed; the server cleans up within the 3-minute example limit"));
}
}
startButton.onclick = async () => {
startButton.disabled = true;
try {
mic = await navigator.mediaDevices.getUserMedia({ audio: true });
const connection = pc = new RTCPeerConnection();
connection.ontrack = event => {
audio.srcObject = event.streams[0] || new MediaStream([event.track]);
audio.play().catch(() => log("Click the play button on the audio control"));
};
connection.onconnectionstatechange = () => {
log(`WebRTC: ${connection.connectionState}`);
};
const events = connection.createDataChannel("oai-events");
events.onmessage = ({ data }) => {
let event;
try { event = JSON.parse(data); } catch { return; }
if (event.type === "session.started") log("Voice session started");
if (event.type === "turn.done" && event.turn?.transcript) {
log(`${event.turn.role}: ${event.turn.transcript}`);
}
if (event.type === "error") log(`Error: ${event.error?.message || data}`);
};
mic.getTracks().forEach(track => connection.addTrack(track, mic));
await connection.setLocalDescription(await connection.createOffer());
if (connection.iceGatheringState !== "complete") {
await new Promise((resolve, reject) => {
const timer = setTimeout(() => reject(new Error("ICE gathering timed out")), 10000);
connection.onicegatheringstatechange = () => {
if (connection.iceGatheringState === "complete") {
clearTimeout(timer);
resolve();
}
};
});
}
const response = await fetch("/session", {
method: "POST",
headers: { "Content-Type": "application/sdp" },
body: connection.localDescription.sdp,
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);
sessionId = result.id;
await connection.setRemoteDescription({ type: "answer", sdp: result.sdp });
stopButton.disabled = false;
log("Speak into the microphone after WebRTC: connected");
} catch (error) {
log(error.message);
await stop();
}
};
stopButton.onclick = stop;
window.addEventListener("pagehide", () => { void stop(); });
</script>
</html>3. Start it and say something
node --env-file=.env server.mjsOpen http://localhost:3000, click "Start voice", allow the microphone, and check in this order:
- The backend prints
sideband: session.started. - The page shows
WebRTC: connected. - Say "Hello, please confirm the voice connection works" and check that the page shows the user and assistant transcripts and that you hear the reply.
- Click "Stop voice" when you are done to release the session and the microphone.
HTTP 201 or WebSocket 101 Switching Protocols alone does not prove voice works. Full success means the session starts, WebRTC connects, your speech is recognized and the reply plays. If the browser blocks autoplay, click the audio control.
The example listens on 127.0.0.1 only. For a multi-user site, serve the page over HTTPS and add login checks, session ownership checks and usage limits for your own users. The example covers direct voice conversation only; letting the assistant run tools or a coding agent requires implementing client delegation.
Voice in the official desktop client
OpenAI states that desktop Voice is not available with API key sign-in; see ChatGPT Voice in Desktop. Signing in to the official desktop client with an API key therefore cannot enable Voice, and the default Codex API key configuration on our console has no voice switch. If you need voice, integrate it in a third-party client that supports this protocol or in your own app.
5. Error reference
Most of these errors mean the method does not match the plan, or the request does not follow the chosen method:
| Error | Cause | Fix |
|---|---|---|
503 No OpenAI Live project key at the configured model level | The plan's upstream is not the official OpenAI API, but /v1/live/sessions was called | On a Codex plan, use method 2 at /v1/live |
Your account does not have access to Quicksilver v2 sessions. | The plan's upstream is the official OpenAI API, but /v1/live was called | Use method 1 at /v1/live/sessions |
AVAS requires OpenAI-Alpha: quicksilver=v2. | Method 2 without the protocol header, or with another value | Add openai-alpha: quicksilver=v2 |
Field session.type must be quicksilver when intent=quicksilver is requested, or architecture="avas" is only supported for quicksilver Realtime WebRTC sessions. | type was set in method 2's session | Remove session.type |
400 Public Live sessions require gpt-live-1 | Method 1's session.model is not gpt-live-1 | Set the model to gpt-live-1 |
400 Live sessions do not accept query parameters; put the model in session.start | Method 1's WebSocket URL has query parameters | Remove them and put the model in session.start |
HTTP 401 | Invalid key, or the key does not belong to this API site | Check the Authorization header and the key |
| Unknown model, no available channel or no model permission | The plan does not include gpt-live-1, or the key's model scope excludes it | Check the plan and the key's model scope |
Method 2's sideband returns 404 | The call_id did not come from this creation response, or the session expired | Take the call_id from this response's Location and use the same API host and key |
| Connected but no input or reply | Microphone permission, device or input level, or the browser blocked autoplay | Check the microphone and the WebRTC/ICE state, and click play |
See Errors for more status codes and WebSocket and Realtime APIs for the API rules.
6. Billing
- OpenAI Live API: billed by session duration. A WebRTC session counts 15 seconds from successful creation and is then deducted by accumulated duration; WebSocket is billed by the seconds the upstream reports. Tokens and tool fees of delegated backend models are billed separately. See the models page for the price.
- Codex Live V3: billed under the rules of your Codex plan, as shown in the console.
7. Before you buy
Both methods work on this site, but each plan supports only one of them:
- To build your own voice app with the OpenAI docs or SDK, or to connect telephone and customer-service systems: choose a plan whose upstream is the official OpenAI API and use method 1.
- To use voice mainly in Codex or in clients that support the Codex Live protocol: choose a Codex plan and use method 2.
Confirm the line of a plan in the console before buying, and ask support if you are unsure. If you already bought a plan that does not match the method you use, adjust using the error reference in section 5.