实时语音

用 gpt-realtime 构建双向语音智能体——模型实时聆听语音并即时用语音回复(就像打电话一样),通过 WebSocket 连接到 /v1/realtime。你现有的 OpenAI Realtime SDK 无需改动即可继续使用;只需把它指向我们的端点,并使用你的 Synthorai key。

ℹ

语音转语音,而非转写
本页介绍语音转语音:语音进、语音出。用 ?model=gpt-realtime 连接。
如果你只需要把音频转成文本(不需要语音回复),请改用语音转文本——那是另一种能力。

端点与认证

在查询字符串里带上模型,向 /v1/realtime 打开一个 WebSocket。认证在升级之前完成,因此被拒绝的 key 根本不会打开 socket。

# WebSocket, server-side (Node / Python / Go — anything that can set headers)
GET wss://synthorai.io/v1/realtime?model=gpt-realtime
Authorization: Bearer $YOUR_KEY
# Send only the Authorization header. Do NOT send OpenAI-Beta: realtime=v1
# (the beta protocol is retired; it makes the upstream reject the session).

你的 sk-syn key 永远不会离开我们的网关——上游凭证在我们这一侧被替换进去。
为服务端客户端设计(Node、Python、Go——任何能设置 Authorization 头的语言)。不支持浏览器端的临时 token。
仅支持 WebSocket。SIP(电话)和 WebRTC 会把客户端直接连到上游,不做代理——请改为把电话音频桥接进 WebSocket。

配置会话

连接打开后,你会收到 session.created。发送一个 session.update 来设置音色、模态、音频格式和轮次检测。请使用 GA 版结构(session.type: "realtime",音频放在 audio.input / audio.output 下)——旧的扁平 beta 结构已废弃。

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "output_modalities": ["audio"],
    "instructions": "You are a concise customer-support agent.",
    "audio": {
      "input":  { "format": { "type": "audio/pcm", "rate": 24000 },
                  "turn_detection": { "type": "server_vad" } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    }
  }
}

一个最小的对话轮次:

用 input_audio_buffer.append 流式发送麦克风音频(base64 PCM)。
用 input_audio_buffer.commit 提交这一轮,然后发送 response.create。
接收音频增量(response.output_audio.delta)和文本转录,然后是带用量的 response.done。
启用 server VAD 后,模型会自动为你检测轮次;相同的事件照常流动,无需手动 commit。

工具、函数调用与知识

在 session.update 里声明函数。模型会在对话中途调用它们——这就是你接入订单查询、工单系统或任何业务系统的方式。返回结果后,模型会带着它继续说话:

// 1. Declare tools in session.update: "tools": [{ "type": "function", ... }]
// 2. The model emits a function_call in response.done.
// 3. Return the result, then ask the model to continue:
{ "type": "conversation.item.create",
  "item": { "type": "function_call_output",
            "call_id": "call_abc",
            "output": "{\"status\":\"shipped\"}" } }
{ "type": "response.create" }

也支持远程 MCP 服务器("type": "mcp")——上游会直接连接到 MCP 服务器。对于知识库,可以通过 instructions、由你的 RAG 支撑的函数工具,或 MCP 来注入事实;模型自带的知识并不是业务事实的可靠来源。

计费

按每次 response.done 的用量以官方刊例价计费(不加价)——音频与文本、输入与输出,并带缓存输入价。每个会话在结束时写入一行台账记录。

类型	输入 / 1M tokens	输出 / 1M tokens
音频	$32 / 1M	$64 / 1M
文本	$4 / 1M	$16 / 1M
缓存输入	$0.40 / 1M	—

所示价格适用于 gpt-realtime / gpt-realtime-2.1;gpt-realtime-2.1-mini 大约是其三分之一。音频输入 ~10 tokens/second,输出 ~20 tokens/second。把对话历史保持为只追加(append-only),就能让缓存价($0.40/1M)吸收长通话的大部分成本。

会话时长与热切换

单个 Realtime 会话最长 60 minutes——这是 OpenAI 平台的限制,不是我们的。到达上限时,上游会关闭连接。

对可能较长的通话,请在远早于上限时热切换(例如在 50 minutes 时):开启一个新会话,并用 conversation.item.create 以文本形式重放对话(用户用 input_text,助手用 output_text——助手的音频无法重放)。
没有会话恢复机制:如果 WebSocket 断开,上游状态就会丢失。重连走的是同一条文本重放路径,所以请从第一天就把重连能力做进去。
gpt-realtime-2.1 / -mini 的上下文为 128K(≈3.5 hours 的输入音频);旧版 gpt-realtime 是 32K——不要用它做长通话。

使用权限

gpt-realtime 处于邀请制内测阶段。它会出现在模型目录和价格中,但要使用它,需要你的工作空间获得授权——请联系我们开通。