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

OpenAI realtime voice waveform and an online assistant interface
Image: OpenAI Realtime API

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 planMethod to useSuitable clients
A plan whose upstream is the official OpenAI APIOpenAI Live APIApps built on the OpenAI docs or SDK, voice customer service, telephone gateways
A Codex planCodex Live V3The 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 APICodex Live V3
Modelgpt-live-1gpt-live-1
WebSocketwss://api.xairouter.com/v1/live/sessions, first frame session.startCreating a session over WebSocket is not supported
WebRTC session creationPOST https://api.xairouter.com/v1/live/sessions, JSON: session + transportPOST https://api.xairouter.com/v1/live, multipart form: sdp + session
Success responseHTTP 201, JSON with session.id and transport.sdpHTTP 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}/attachwss://api.xairouter.com/v1/live/{call_id}
AuthenticationAuthorization: Bearer <API key>Authorization: Bearer <API key>
Protocol headerNoneopenai-alpha: quicksilver=v2 (required)
session.typeNot neededDo not set it
Main eventssession.started, session.input_transcript.delta, session.output_transcript.delta, session.output_audio.delta, session.closedsession.started, input_transcript.added, output_transcript.added, turn.done
DetailsSection 3; OpenAI Live guideSection 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/completions and ordinary /v1/responses requests never become Live voice. Adding a chat model with the same name to a client does not give it voice either.
  • HTTP 201 only 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

FieldDescription
modelRequired, gpt-live-1; cannot be changed after start
instructionsConversation instructions
audio.output.voiceVoice, default marin
audio.formatWebSocket only, for example {"type": "audio/pcm", "rate": 24000}; WebRTC negotiates it in SDP, so do not set it
delegationOptional, 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 websockets

The 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.py

Key points:

  • The first message after connecting must be session.start. Send audio only after session.started arrives.
  • 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.close and wait for session.closed before 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:

WebSocketWebRTC
Sessionsession.started receivedHTTP 201, WebRTC connected, session.started on the data channel
User transcriptQuestion recognized correctlyQuestion recognized correctly
Model replyTranscript and audio output normalTranscript and remote audio track normal
Endsession.closed, reason close_requestedSame

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 capabilityUsable with this method?
Custom Live address, WebRTC SDP, a sideband on the same call_id, and Live V3 eventsYes, as long as the key can access the model
Only Base URL, API key and chat model settingsThe client needs Live voice protocol support
Only creating new voice sessions directly over WebSocketNo; the Codex line supports WebRTC plus sideband only
Only the official OpenAI Live API or the Realtime protocolRequest bodies and events cannot be mixed; for the official protocol, choose the plan for method 1
Only speech-to-text or text-to-speechThese are separate ASR/TTS APIs, not Live conversation

Parameters

ParameterValue
Create a sessionPOST https://api.xairouter.com/v1/live, multipart form: sdp + session
Sideband for the same sessionwss://api.xairouter.com/v1/live/{call_id}
Authentication headerAuthorization: Bearer <your API key>
Protocol headeropenai-alpha: quicksilver=v2 (for both session creation and the sideband)
ModelSet session.model to gpt-live-1 explicitly
session.typeDo not set it
Example voicecove

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

  1. The browser or native client gets the microphone and creates a WebRTC offer SDP with an audio track and an oai-events data channel.
  2. Your backend sends sdp and session as a multipart form to /v1/live, with the key and the protocol header.
  3. Success is HTTP 201; the body is the answer SDP and Location contains the new session's call_id.
  4. Your backend opens the sideband at /v1/live/{call_id} and waits for session.started; the browser applies the answer SDP to complete the WebRTC connection.
  5. Audio goes over WebRTC; transcripts and turns arrive as input_transcript.added, output_transcript.added, turn.done and similar events. To finish, send session.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@8

Create .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_key

1. 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.mjs

Open http://localhost:3000, click "Start voice", allow the microphone, and check in this order:

  1. The backend prints sideband: session.started.
  2. The page shows WebRTC: connected.
  3. 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.
  4. 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:

ErrorCauseFix
503 No OpenAI Live project key at the configured model levelThe plan's upstream is not the official OpenAI API, but /v1/live/sessions was calledOn 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 calledUse method 1 at /v1/live/sessions
AVAS requires OpenAI-Alpha: quicksilver=v2.Method 2 without the protocol header, or with another valueAdd 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 sessionRemove session.type
400 Public Live sessions require gpt-live-1Method 1's session.model is not gpt-live-1Set the model to gpt-live-1
400 Live sessions do not accept query parameters; put the model in session.startMethod 1's WebSocket URL has query parametersRemove them and put the model in session.start
HTTP 401Invalid key, or the key does not belong to this API siteCheck the Authorization header and the key
Unknown model, no available channel or no model permissionThe plan does not include gpt-live-1, or the key's model scope excludes itCheck the plan and the key's model scope
Method 2's sideband returns 404The call_id did not come from this creation response, or the session expiredTake the call_id from this response's Location and use the same API host and key
Connected but no input or replyMicrophone permission, device or input level, or the browser blocked autoplayCheck 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.

References