跳到主要内容

创建实时会话

POST 
/v1/realtime/sessions

为发起调用的终端用户开启一个语音会话——或者带上 session_id，重新加入该用户尚未结束的某个会话——并返回会话的 id 和一个短期有效的 client_secret。

在 client_secret.expires_at 之前打开到 websocket_url 的 WebSocket，并把密钥放在 Authorization: Bearer 请求头里。浏览器无法设置这个请求头，所以改为提供两个子协议：neweyes-realtime 和 neweyes-secret. 后接密钥。一个密钥只能打开一条连接。

语音会话和其他会话一样：通过 /v1/sessions 读取它、它的转写内容和纪要。连接关闭并不会结束会话：要继续通话，请带上它的 session_id 创建实时会话以获取新的密钥，然后重新连接——对话会从中断的地方继续。一个会话同一时间只由一条连接持有；较新的连接会接管它。用 POST /v1/realtime/sessions/\{session_id\}/end 结束会话。没有连接的会话会自行结束，但绝不会早于其最后一条连接关闭后的 10 分钟——这个时间可能变长，但不会缩短。在那之后重新加入会被拒绝，返回 session_ended：请开启新的会话。会话结束后会生成它的纪要。

语音助手可能调用两个工具，它们以 tool_call 帧送达，由你的客户端执行，并用 tool_result 答复：

  • create_task — 把它的 task 文字作为消息发到一个文字会话（POST /v1/sessions，或在你为这次通话保留的会话上 POST /v1/sessions/{session_id}/messages），并用返回的 task_id 答复。任务的进度和回复会在 GET /v1/sessions/{session_id}/events 上送达。
  • get_task_status — 用那条事件流上该任务的情况答复：仍在运行，或已经结束（完成并附回复、已停止或失败）。

新的语音会话和文字会话一样，打开你用 capabilities 或 exclude_capabilities 选择的能力，并在整个生命周期里保留它们；重新加入时也沿用这些能力，所以两个字段都不传。语音助手会被告知会话没开哪些能力，因此不会提议、也不会委托这些能力——但任务所在的文字会话由你来创建，通话的选择不会带到它上面：请用同样的 capabilities 或 exclude_capabilities 创建它，否则它会打开全部能力。无法读取能力的通话不会开始：它会以 1011 关闭。

你的客户端发送的帧在以下情况会被丢弃，且没有任何回复：超过 4 MiB；音频或图片的 data 不是 base64；input_text 超过 32,000 个字符或含有 NUL 字符；tool_result 的 output 以 JSON 计超过 32,000 个字符。

套接字没有请求体或响应体，所以连接的结果由 WebSocket 关闭码说明：

  • 1000 — 正常关闭，或会话已被结束。
  • 1001 — 离开：一方正在结束会话（底层会话终止时也可能转发这个关闭码）。
  • 1011 — 服务端错误，或语音服务暂时不可用；请稍后重试。语音服务发来的关闭码如果不在此列，也会以这个关闭码送达。
  • 1012 — 服务端正在为计划内的重新部署而重启；请稍后重连。
  • 4001 — 密钥缺失、无效、过期或已被使用，其会话已被删除或已结束，或者调用方的访问已被撤销；请获取新的密钥（会话尚未结束时，使用同一个 session_id）。
  • 4009 — 较新的连接接管了这个会话；不要从这个连接重连，否则两个连接会轮流抢占会话。
  • 4401 — 鉴权失败，或账号不是有效状态。
  • 4429 — 计费账户的积分已用完，或已有太多语音会话处于活动状态；请加上积分或关闭其中一个，然后重试。

请求​

响应​

成功响应