gpt-live-1 接入指南:用 OpenAI 官方 Live API 调用全双工语音
Posted November 20, 2026 by XSI 技术团队 ‐ 8 min read

gpt-live-1 是 OpenAI 的全双工语音模型:它能同时听和说,用户可以随时插话,模型自己判断什么时候停、什么时候接;需要推理、查资料或调用工具时,再把任务交给后端模型。它适合语音客服、电话机器人、语音助手、陪练和导览这类需要来回对话的场景。
在 XSI Router 上,gpt-live-1 按 OpenAI 官方 Live API 提供:接口、请求体和事件与 OpenAI 官方文档一致,只需把地址换成 api.xsirouter.com、Key 换成本站 Key。上游由平台提供,注册充值即可使用,无需自备 OpenAI Key。
一、接入参数
| 参数 | 本站取值 |
|---|---|
| 模型 | gpt-live-1 |
| WebSocket | wss://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.startedsession.input_transcript.deltasession.output_transcript.deltasession.output_audio.deltasession.usage.updatedsession.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:
| WebSocket | WebRTC | |
|---|---|---|
| 建立会话 | 收到 session.started | HTTP 201,WebRTC 连通,数据通道收到 session.started |
| 用户语音转写 | 正确识别提问 | 正确识别提问 |
| 模型回复 | 转写与语音输出正常 | 转写与远端音轨正常 |
| 结束 | session.closed,原因 close_requested | 同左 |
WebSocket 验证使用的就是上面的 Python 脚本;WebRTC 验证使用 Python 的 aiortc 客户端,上面的 Node.js 与浏览器代码按相同流程编写,部署前请在自己的浏览器中再验证一次。委派后端、中文语音和打断未在本次验证范围内。
三、常见报错
| 报错 | 原因 | 处理 |
|---|---|---|
HTTP 401 | Key 无效,或 Key 与 API 站点不匹配 | 检查 Authorization 请求头与 Key |
400 Public Live sessions require gpt-live-1 | session.model 不是 gpt-live-1 | 把模型设为 gpt-live-1 |
400 Live sessions do not accept query parameters; put the model in session.start | WebSocket 地址带了查询参数 | 去掉查询参数,模型写在 session.start 中 |
400 Live requires transport.type=webrtc and transport.sdp | WebRTC 请求体缺少 transport | 按示例提交 transport.type 与浏览器生成的 transport.sdp |
| 账号余额或额度不足 | 未充值或额度用尽 | 在控制台充值 |
更多状态码见《错误码》,接口规则见《WebSocket 与实时接口》。
四、计费
- 按会话时长计费:WebRTC 会话在建会成功后起计 15 秒,之后按累计时长抵扣;WebSocket 按上游上报的秒数计费。
- 委派给后端模型的 Token 和工具费用另计。
- 单价见模型页。
五、开始使用
- 在 manage.xsirouter.com 用邮箱注册并激活,页面会显示你的 API Key。
- 在控制台充值。
- 把上面示例中的
XSI_API_KEY换成你的 Key,先用 WebSocket 脚本跑通一次语音问答,再接入自己的应用。
上游 OpenAI Key 由平台提供,你不需要申请 OpenAI 项目或开通 Live 权限。企业接入和私有化部署请见企业服务。