Realtime WebSocket 接入 #

Realtime 用于低延迟语音、文本和工具调用交互。它不是普通 HTTP 流式接口，也不是 /v1/chat/completions 的 stream: true。客户端需要建立 WebSocket 连接。

接口信息 #

Realtime 必须在 URL 查询参数里带上 model。例如：

wss://api.corerouter.tech/v1/realtime?model=realtime-model-id

服务端连接方式 #

如果你的程序运行在服务端，优先使用 Authorization Header。这样 API Key 不会暴露给浏览器用户。

import WebSocket from "ws";

const apiKey = process.env.COREROUTER_API_KEY;
const url = "wss://api.corerouter.tech/v1/realtime?model=realtime-model-id";

const ws = new WebSocket(url, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      modalities: ["text"],
      instructions: "你是一个简洁的实时助手。",
    },
  }));

  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [
        { type: "input_text", text: "你好，请用一句话介绍 CoreRouter。" }
      ],
    },
  }));

  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.on("message", (data) => {
  console.log(data.toString());
});

安装依赖：

npm install ws

浏览器或官方 Realtime SDK 风格连接 #

浏览器 WebSocket 不能自定义 Authorization Header。一些 Realtime SDK 会把 API Key 放到 Sec-WebSocket-Protocol 子协议里：

realtime, openai-insecure-api-key.sk-xxxxxxxxxxxxxxxx

如果你必须这样接入，请注意：

• API Key 会出现在浏览器运行环境里，不适合生产环境直接使用。
• 推荐由你自己的服务端签发短期会话或反向代理 Realtime 请求。
• 只在可信环境或本地测试时使用长期 API Key。

最小事件流程 #

常见文本会话流程如下：

1. 建立 WebSocket 连接。
2. 发送 session.update 设置模型行为、输入输出类型、音色和工具。
3. 发送 conversation.item.create 写入用户消息。
4. 发送 response.create 触发模型回复。
5. 持续接收服务端事件，例如文本增量、音频增量、工具调用或 response.done。

音频输入 #

音频通常通过 input_audio_buffer.append 发送 Base64 编码后的音频片段。音频格式要和 session.update 里的 input_audio_format 保持一致。

{
  "type": "input_audio_buffer.append",
  "audio": "base64-audio-chunk"
}

不同 Realtime 模型支持的采样率、编码、音色和转写能力不同，请以控制台模型说明为准。

常见问题 #

• 连接时报 401：检查 API Key 是否完整；如果使用 Sec-WebSocket-Protocol，确认包含 openai-insecure-api-key.sk-...。
• 连接时报 404 或模型不存在：确认 URL 里 model=realtime-model-id 是控制台中的 Realtime 模型。
• 能连接但没有回复：确认已发送 response.create，并检查 session.update 是否设置了可用的 modalities。
• 浏览器连接失败：检查跨域、代理是否支持 WebSocket，以及是否使用了服务端代理保护 API Key。
• 普通聊天模型不可用：Realtime 需要专门的 Realtime 模型或渠道，不能直接复用普通聊天模型。