gpt-live-1 接入指南:用 OpenAI 官方 Live API 调用全双工语音

Posted November 20, 2026 by XSI 技术团队 ‐ 8 min read

OpenAI 实时语音波形与在线助手界面
配图:OpenAI Realtime API

gpt-live-1 是 OpenAI 的全双工语音模型:它能同时听和说,用户可以随时插话,模型自己判断什么时候停、什么时候接;需要推理、查资料或调用工具时,再把任务交给后端模型。它适合语音客服、电话机器人、语音助手、陪练和导览这类需要来回对话的场景。

在 XSI Router 上,gpt-live-1 按 OpenAI 官方 Live API 提供:接口、请求体和事件与 OpenAI 官方文档一致,只需把地址换成 api.xsirouter.com、Key 换成本站 Key。上游由平台提供,注册充值即可使用,无需自备 OpenAI Key。

一、接入参数

参数本站取值
模型gpt-live-1
WebSocketwss://api.xsirouter.com/v1/live/sessions,连接后首帧发送 session.start
WebRTC 创建会话POST https://api.xsirouter.com/v1/live/sessions,JSON 请求体包含 session 与 transport
附着同一会话(sideband)wss://api.xsirouter.com/v1/live/sessions/{id}/attach
鉴权Authorization: Bearer <你的 API Key>
主要事件session.started
session.input_transcript.delta
session.output_transcript.delta
session.output_audio.delta
session.usage.updated
session.closed

通用要求:

  • API Key 只能放在服务端,不要写进浏览器或 App。浏览器端用 WebRTC,由你的后端代为创建会话。
  • gpt-live-1 只支持 Live 接口。/v1/chat/completions、/v1/responses 和 Realtime 接口都不能调用它。
  • 收到 HTTP 201 只说明会话已创建。完整的成功标准是:会话开始、用户语音被转写、能听到模型的回复。

二、调用方式

会话配置

字段说明
model必填,gpt-live-1;启动后不能修改
instructions对话指令
audio.output.voice音色,默认 marin
audio.format仅 WebSocket 需要,如 {"type": "audio/pcm", "rate": 24000};WebRTC 由 SDP 协商,不要设置
delegation可选,client 或 responses,用于把推理和工具调用交给后端

WebSocket 音频为 Base64 编码的 PCM:默认 24 kHz、单声道、16 位小端,不带 WAV 文件头。也支持 16 kHz PCM,以及 8 kHz 的 G.711 μ-law(audio/pcmu)和 A-law(audio/pcma)。

WebSocket 示例(Python)

适合服务端、电话网关和测试。准备 Python 3.9 或更新版本,安装依赖:

pip install websockets

下面的脚本读取一个 24 kHz、单声道、16 位的 WAV 文件作为用户语音,打印双方转写,并把模型的语音回复保存为 reply.wav:

import asyncio, base64, json, os, wave
import websockets

URL = "wss://api.xsirouter.com/v1/live/sessions"
KEY = os.environ["XSI_API_KEY"]
CHUNK = 4800  # 0.1 秒 @ 24 kHz / 16 位


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": "你是一个简洁友好的语音助手,用一句话回答。",
                "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("错误:", raw)
                elif kind == "session.closed":
                    print("会话结束:", 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)]
        # 按真实速度推送:先发问题音频,再发 8 秒静音,留出回答时间
        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("用户:", "".join(heard))
    print("助手:", "".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())

运行:

XSI_API_KEY=替换为你的_API_Key python3 live_ws.py

要点:

  • 连接后第一条消息必须是 session.start,收到 session.started 之后再推送音频。
  • 音频要大致按真实时间节奏推送。全双工模型按时间在听,一次性灌入整段音频的效果不可预期。
  • 结束时先发 session.close,等收到 session.closed 再断开,这样才能拿到完整的用量。

WebRTC 示例(浏览器 + Node.js 后端)

适合网页和 App。浏览器生成 SDP offer,交给你的后端;后端带着 Key 调用 POST /v1/live/sessions,再把 answer SDP 返回给浏览器。音频走 WebRTC 媒体轨道,事件走名为 oai-events 的数据通道。

后端 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) => {
  // 生产环境请在这里做用户登录校验、限流和 Origin 检查
  const upstream = await fetch("https://api.xsirouter.com/v1/live/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.XSI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      session: {
        model: "gpt-live-1",
        instructions: "你是一个简洁友好的中文语音助手。",
        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("打开 http://localhost:3000"));

页面 public/index.html 中的脚本(需 HTTPS 或 localhost,并由用户点击触发):

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));

  // 数据通道必须在 createOffer 之前创建
  const events = pc.createDataChannel("oai-events");
  events.onmessage = ({ data }) => {
    const event = JSON.parse(data);
    if (event.type === "session.input_transcript.delta") console.log("我:", event.delta);
    if (event.type === "session.output_transcript.delta") console.log("助手:", 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 });

  // 挂断:发送 session.close,收到 session.closed 后再释放连接和麦克风
  return () => events.send(JSON.stringify({ type: "session.close" }));
}

WebRTC 下不要在数据通道上发送 session.start 或 session.input_audio.append:HTTP 请求本身就会启动会话,音频全部走媒体轨道。

验证结果

2026 年 11 月 20 日,我们通过 api.xsirouter.com,用一段合成的英文提问语音分别验证了 WebSocket 和 WebRTC:

WebSocketWebRTC
建立会话收到 session.startedHTTP 201,WebRTC 连通,数据通道收到 session.started
用户语音转写正确识别提问正确识别提问
模型回复转写与语音输出正常转写与远端音轨正常
结束session.closed,原因 close_requested同左

WebSocket 验证使用的就是上面的 Python 脚本;WebRTC 验证使用 Python 的 aiortc 客户端,上面的 Node.js 与浏览器代码按相同流程编写,部署前请在自己的浏览器中再验证一次。委派后端、中文语音和打断未在本次验证范围内。

三、常见报错

报错原因处理
HTTP 401Key 无效,或 Key 与 API 站点不匹配检查 Authorization 请求头与 Key
400 Public Live sessions require gpt-live-1session.model 不是 gpt-live-1把模型设为 gpt-live-1
400 Live sessions do not accept query parameters; put the model in session.startWebSocket 地址带了查询参数去掉查询参数,模型写在 session.start 中
400 Live requires transport.type=webrtc and transport.sdpWebRTC 请求体缺少 transport按示例提交 transport.type 与浏览器生成的 transport.sdp
账号余额或额度不足未充值或额度用尽在控制台充值

更多状态码见《错误码》,接口规则见《WebSocket 与实时接口》。

四、计费

  • 按会话时长计费:WebRTC 会话在建会成功后起计 15 秒,之后按累计时长抵扣;WebSocket 按上游上报的秒数计费。
  • 委派给后端模型的 Token 和工具费用另计。
  • 单价见模型页。

五、开始使用

  1. 在 manage.xsirouter.com 用邮箱注册并激活,页面会显示你的 API Key。
  2. 在控制台充值。
  3. 把上面示例中的 XSI_API_KEY 换成你的 Key,先用 WebSocket 脚本跑通一次语音问答,再接入自己的应用。

上游 OpenAI Key 由平台提供,你不需要申请 OpenAI 项目或开通 Live 权限。企业接入和私有化部署请见企业服务。

参考资料