Realtime 实时语音

WSS wss://agg.kailin.com.cn/v1/realtime

基于 WebSocket 的实时双向语音对话接口（OpenAI Realtime 协议），适合语音助手、实时翻译等低延迟场景。

连接

模型名通过查询参数传递，鉴权与 HTTP 接口相同：

wss://agg.kailin.com.cn/v1/realtime?model=gpt-4o-realtime-preview

const ws = new WebSocket(
  'wss://agg.kailin.com.cn/v1/realtime?model=gpt-4o-realtime-preview',
  {
    headers: {
      Authorization: 'Bearer sk-你的令牌',
      'OpenAI-Beta': 'realtime=v1',
    },
  }
);

备注

浏览器端 new WebSocket 无法自定义请求头，此时可通过 Authorization 以外的子协议参数透传令牌，或由你自己的后端代理 WebSocket 连接（推荐，避免令牌暴露在前端）。

消息格式

所有消息为 JSON 文本帧，均有 type 字段区分。

会话建立

连接成功后服务端推送 session.created，客户端通常先发送 session.update 配置语音与模式：

{
  "type": "session.update",
  "session": {
    "instructions": "你是一个语音助手，回答保持简短。",
    "voice": "alloy",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_transcription": { "model": "whisper-1" },
    "turn_detection": { "type": "server_vad" }
  }
}

发送用户音频

音频以 Base64 编码的 PCM16（24kHz 单声道）分块发送：

{ "type": "input_audio_buffer.append", "audio": "<base64 pcm16>" }

{ "type": "input_audio_buffer.commit" }

开启 server_vad 后服务端自动检测说话结束并回提交，无需手动 commit。

触发回复

{
  "type": "response.create",
  "response": { "modalities": ["text", "audio"], "instructions": "热情一点。" }
}

接收服务端事件

事件	说明
session.created / session.updated	会话建立/配置生效
input_audio_buffer.speech_started / _stopped	VAD 检测到说话开始/结束
input_audio_buffer.committed	音频缓冲已提交
conversation.item.created	会话条目（消息）创建
response.audio_transcript.delta / _done	回复的文本转写增量/完成
response.audio.delta / _done	回复音频增量（Base64 PCM16）
response.text.delta / _done	纯文本回复增量
response.done	本轮回复结束
error	错误事件

完整流程示例

const ws = new WebSocket(url);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: { voice: 'alloy', turn_detection: { type: 'server_vad' } },
  }));
  // 发送一段音频…
  ws.send(JSON.stringify({
    type: 'input_audio_buffer.append',
    audio: btoa(String.fromCharCode(...pcmChunk)),
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'response.audio.delta':
      playPcmChunk(atob(msg.delta));
      break;
    case 'response.audio_transcript.delta':
      appendSubtitle(msg.delta);
      break;
    case 'response.done':
      console.log('本轮结束', msg.response.usage);
      break;
  }
};

警告

Realtime 接口按音频时长计费，费用显著高于文本接口，调试时注意控制会话时长。是否可用取决于渠道配置的模型列表。