登录注册
API 文档实时语音

API 文档 / OpenAI 格式

实时语音

GEThttps://api.tokenjoy.org/v1/realtime

建立一条 WebSocket 连接进行实时语音对话，与 OpenAI Realtime API（GA 版）兼容。连接建立后，双方都发送 JSON 文本消息（事件），每条消息都有 type 字段。使用方法见 API 指南 · 实时语音。

连接参数

参数位置说明
model查询参数必填。gpt-realtime 或 gpt-realtime-mini
Authorization请求头Bearer <你的 API Key>。不支持把 Key 放在地址或 WebSocket 子协议里

客户端事件（你发送的）

事件说明
session.update设置会话：instructions（系统提示）、output_modalities（["audio"] 或 ["text"]）、audio.output.voice（音色，如 marin、alloy）、audio.input.turn_detection（语音检测，null 为关闭）、tools（函数调用）。session.type 固定为 realtime
input_audio_buffer.append追加一段音频，audio 为 base64 编码的 PCM
input_audio_buffer.commit把已追加的音频提交为一条用户消息（关闭语音检测时使用）
input_audio_buffer.clear清空还没提交的音频
conversation.item.create添加一条消息，例如文字输入 {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "..."}]}，或函数调用的结果
response.create请求模型回答
response.cancel打断正在进行的回答（例如用户插话）

服务端事件（你收到的）

事件说明
session.created连接建立后的第一条消息，带有会话的默认设置
session.updatedsession.update 生效后返回
input_audio_buffer.speech_started语音检测开启时，检测到用户开始说话（可以借此停止播放、打断回答）
response.output_audio.delta一段语音，delta 为 base64 编码的 PCM
response.output_audio_transcript.delta语音回答对应的文字稿片段
response.output_text.deltaoutput_modalities 为 ["text"] 时的文字片段
response.function_call_arguments.done模型要调用的函数及参数
response.done一轮回答结束，response.usage 是本轮用量，按它计费
error请求出错，error.message 说明原因；连接一般不会因此断开

用量

response.done 中的 usage：缓存部分包含在输入总数之内，文字和音频分开列出。

"usage": {
  "total_tokens": 1500,
  "input_tokens": 1000,
  "output_tokens": 500,
  "input_token_details": {
    "text_tokens": 200, "audio_tokens": 800, "image_tokens": 0,
    "cached_tokens": 300,
    "cached_tokens_details": {
      "text_tokens": 100, "audio_tokens": 200, "image_tokens": 0
    }
  },
  "output_token_details": { "text_tokens": 100, "audio_tokens": 400 }
}

连接失败与关闭

情况含义
握手返回 401Key 缺失或无效
握手返回 402 / 429余额用完，或上游暂时繁忙（429 时请稍后重试，见限速与隔离）
关闭码 1000正常结束
关闭码 1001，原因 maximum call duration reached连接达到时长上限（默认 60 分钟），重新连接即可
关闭码 1008余额用完或 Key 被停用、重置，充值或换用新 Key 后重新连接
关闭码 1011上游出错，可以重新连接

其他错误码见错误码。

上一页向量