实时会话 — OpenAI Realtime 协议

WS/v1/realtime

通过 WebSocket 建立实时会话，进行低延迟语音对话或文本流式对话。

Bearer Token

模型介绍

OpenAI Realtime API 是业界主流的实时对话协议，支持全双工音频流与文本流。宁享Token 的 /v1/realtime 提供 WebSocket 透传接入：握手与鉴权由本平台处理，session.update 等事件语义与响应事件集合均由上游模型决定（我方不做重命名、不补发）。

支持模型

⚠️ 本页表格所列模型名（realtime-glm-5.2 / realtime-doubao）与下方示例所用模型名（glm-realtime-flash）互相矛盾，且均未在 NX-api 代码与生产定价快照中登记（未取证）。实时会话渠道当前未开通：模型无可用渠道时，握手之前即返回 HTTP 503 model_not_found。渠道开通并以 GET /v1/models 实证后，再将本表与下方三处示例统一到同一组真实模型名。

模型	输入	输出	说明
realtime-glm-5.2	音频+文本	音频+文本	智谱实时对话（未取证）
realtime-doubao	音频+文本	音频+文本	豆包实时对话（未取证）

连接建立

WebSocket URL

wss://api.nxtoken.cn/v1/realtime?model=<model_id>

鉴权

通过 WebSocket 子协议传递 token（子协议数组必须同时含 realtime 与 openai-insecure-api-key.<YOUR_API_KEY>；只发 realtime 会鉴权失败返回 401）：

const ws = new WebSocket(
  "wss://api.nxtoken.cn/v1/realtime?model=glm-realtime-flash",
  ["realtime", "openai-insecure-api-key.<YOUR_API_KEY>"]
);

注意：示例主机 api.nxtoken.cn 在 WebSocket 场景下须使用 wss:// 前缀（HTTP 场景为 https://）。

请求参数

session.update

连接建立后，客户端可通过发送 session.update 配置会话：

session.update 参数

⚠️ 本表「默认值」列为上游协议口径，未在官方基线与 NX-api 代码中登记（未取证）：我方不注入、不覆盖任何 session 字段，实际生效值以上游为准（我方仅将输入 / 输出音频格式的本地计费口径固定为 pcm16）。max_response_output_tokens 我方未建模，仅原样透传。

参数	类型	必填	默认值	描述
session	object	是	-	会话配置对象
session.modalities	array<string>	否	["text","audio"]	模态，可选 text、audio
session.instructions	string	否	-	系统指令
session.voice	string	否	tongtong	音色：tongtong / female-tianmei / male-qn-daxuesheng / male-qn-jingying / lovely_girl / female-shaonv
session.input_audio_format	string	否	pcm16	输入音频格式
session.output_audio_format	string	否	pcm16	输出音频格式
session.input_audio_transcription	object	否	-	输入音频转录配置
session.turn_detection	object	否	-	VAD 配置，{"type":"server_vad"} 启用服务端 VAD
session.tools	array	否	-	函数调用定义
session.tool_choice	string	否	auto	函数调用策略
session.temperature	number	否	0.8	采样温度
session.max_response_output_tokens	integer	否	-	单次响应最大输出 token 数

请求示例

基本会话

import asyncio, json, base64, websockets

async def main():
    uri = "wss://api.nxtoken.cn/v1/realtime?model=glm-realtime-flash"
    async with websockets.connect(
        uri, subprotocols=["realtime", "openai-insecure-api-key.<YOUR_API_KEY>"]
    ) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "modalities": ["text", "audio"],
                "instructions": "你是一个友好的助手。",
                "input_audio_format": "pcm16",
                "output_audio_format": "pcm16",
                "turn_detection": {"type": "server_vad"},
            },
        }))

        async for raw in ws:
            msg = json.loads(raw)
            print(msg["type"], msg)

asyncio.run(main())

const ws = new WebSocket(
  "wss://api.nxtoken.cn/v1/realtime?model=glm-realtime-flash",
  ["realtime", "openai-insecure-api-key.<YOUR_API_KEY>"]
);

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      modalities: ["text", "audio"],
      instructions: "你是一个友好的助手。",
      voice: "tongtong",
      input_audio_format: "pcm16",
      output_audio_format: "pcm16",
      turn_detection: { type: "server_vad" },
    },
  }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg);
});

发送音频

// 将麦克风采集到的 PCM 数据转为 Base64 后发送
function sendAudio(pcmBuffer) {
  ws.send(JSON.stringify({
    type: "input_audio_buffer.append",
    audio: pcmBuffer.toString("base64"),
  }));
}

提交对话轮次

// 触发模型对已发送的音频进行回复
ws.send(JSON.stringify({ type: "input_audio_buffer.commit" }));
ws.send(JSON.stringify({ type: "response.create" }));

发送文本

ws.send(JSON.stringify({
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [{ type: "input_text", text: "你好" }],
  },
}));
ws.send(JSON.stringify({ type: "response.create" }));

响应事件

⚠️ 下表为上游发送的事件集合，宁享Token 原样转发、不重命名也不补发（我方仅自行发送 error）。OpenAI GA 版本已把 response.audio.* / response.text.* 更名为 response.output_audio.* / response.output_text.*，实际收到的名字取决于上游模型。

type	含义
session.created	会话已建立
session.updated	会话已更新
input_audio_buffer.speech_started	检测到用户开始说话
input_audio_buffer.speech_stopped	检测到用户停止说话
input_audio_buffer.committed	音频已提交
conversation.item.created	对话项已创建
response.created	响应开始
response.audio.delta	音频分片（Base64）
response.audio.done	音频流结束
response.text.delta	文本分片
response.text.done	文本流结束
response.function_call_arguments.delta / response.function_call_arguments.done	函数调用参数流
response.done	响应完成
error	错误

注意事项

• 音频格式为 PCM 24kHz 16-bit 单声道，需自行封装或从麦克风采集。
• 全双工模式下，服务端 VAD 会自动检测用户说话的起止点并触发响应。
• 入口网关读超时为 300s：空闲 5 分钟会被断开，请在客户端实现重连与心跳。
• 函数调用：模型触发 response.function_call_arguments.done，客户端执行后通过 conversation.item.create 回传 function_call_output。
• 计费：按 token 计费（音频 token 由音频时长换算），输入音频与输出音频分别乘音频倍率与音频补全倍率；文本按 token 计费。
• 非 WebSocket 客户端访问该路径只会得到 HTTP 400 Bad Request（纯文本）或 503 model_not_found（模型无可用渠道时，发生在握手之前）。