实时语音（Realtime）接口

接口说明

Realtime 接口通过 WebSocket 建立长连接，围绕事件流进行会话控制、音频上传与响应接收。适用于语音助手、同传、语音客服等低延迟场景。

该接口不是标准 REST 请求。你需要支持 WebSocket 的客户端（浏览器、Node.js、websocat、SDK）发起连接。

认证

可通过 URL 查询参数或 Authorization 请求头传递令牌：

方式	格式	说明
查询参数	`?token=sk-xxxxxx`	在 WebSocket URL 中附加 token 参数
请求头	`Authorization: Bearer sk-xxxxxx`	更推荐的方式，避免令牌出现在 URL 日志中

连接参数

参数	类型	必需	说明
`model`	string (query)	是	模型名称，如 `gpt-4o-realtime-preview`
`token`	string (query)	否	仅在使用 URL 鉴权时传入；若用 Header 可省略

连接 URL 构造器

可快速拼出可连接的 WebSocket 地址，并生成对应的 websocat 命令。

服务器地址

模型

Token

鉴权方式

WebSocket URL

websocat 示例

最小事件流程

推荐按以下顺序串联事件，先打通最小闭环再扩展功能。

1

建立连接

连接 wss://.../v1/realtime?model=... 并完成鉴权。

2

发送 session.update

配置语音、模态、VAD、系统提示词等会话参数。

3

上传音频缓冲

发送 input_audio_buffer.append，结束后发送 input_audio_buffer.commit。

4

触发生成

发送 response.create 请求模型输出。

5

接收增量结果

处理 response.audio.delta / response.text.delta，直到 response.done。

连接示例

JavaScript

            const ws = new WebSocket(
  'wss://your-base-url/v1/realtime?model=gpt-4o-realtime-preview',
  ['realtime', 'openai-insecure-api-key.sk-xxxxxx', 'openai-beta.realtime-v1']
);

ws.onopen = function () {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: {
      modalities: ['text', 'audio'],
      instructions: '你是一个友好的语音助手',
      voice: 'alloy',
      input_audio_format: 'pcm16',
      output_audio_format: 'pcm16',
      turn_detection: {
        type: 'server_vad'
      }
    }
  }));
};

ws.onmessage = function (event) {
  const data = JSON.parse(event.data);
  switch (data.type) {
    case 'session.created':
      console.log('会话已创建');
      break;
    case 'response.audio.delta':
      // 播放音频增量
      break;
    case 'response.text.delta':
      // 渲染文本增量
      break;
  }
};
          

事件类型

常见事件如下，建议先实现核心事件再逐步补齐边界事件。

事件	方向	说明
`session.update`	客户端 → 服务端	更新会话配置（语音、模态、指令等）
`session.created`	服务端 → 客户端	会话创建成功
`input_audio_buffer.append`	客户端 → 服务端	追加音频帧到输入缓冲区
`input_audio_buffer.commit`	客户端 → 服务端	提交音频缓冲区，准备推理
`response.create`	客户端 → 服务端	触发模型生成响应
`response.audio.delta`	服务端 → 客户端	音频响应增量数据
`response.text.delta`	服务端 → 客户端	文本响应增量数据
`response.done`	服务端 → 客户端	本轮响应结束

常见错误响应

401 Unauthorized

            {
  "error": {
    "message": "invalid api key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
          

409 Conflict

            {
  "error": {
    "message": "session has reached concurrency limit",
    "type": "rate_limit_error",
    "param": null,
    "code": "session_limit_exceeded"
  }
}
          