OneSay开发者

搜索文档目录

OneSay平台

更新日志

预览版：功能和API可能会变化。

2026-10-27：多人语音房间和OneSay Agent更稳定
  • 多人语音房间：修复了在其他人已经在说话的房间中加入和收听时的问题。服务器繁忙时，控制台会自动重试这一步，最多3次，并显示正在重试。
  • 多人语音房间：只提供你自己的麦克风音频源，不再列出同一环境中其他人的音频源。
  • OneSay Agent对话不再在约38秒后结束。
  • 停止Agent后，一旦停止得到确认，读取Agent运行会返回stopped和effective_stopped_at，不再一直停留在pending。控制台会替你读回。
  • 关闭房间时如果遇到服务重启，会自动重试，已关闭的房间不再一直占用环境的活跃房间名额。
2026-10-27：文档和控制台更易读
  • 比屏幕宽的文档表格，会在还能滚动的一侧显示渐隐效果，适用于文档、示例、本更新日志和社区页面。表格中的标识符不再从名称中间断行。
  • 在窄屏上，标题的#链接与标题保持在同一行，面包屑不再在行尾留下分隔符，上一篇和下一篇链接的“上一篇”“下一篇”单独显示在页面标题上方。
  • 控制台的各个视图改为标签页：用方向键在标签之间移动，按Enter打开。
  • 开发者中心、文档和控制台的中文和日文文本已重新检查，日文现在遵循统一的风格指南和术语表。
2026-10-26：多人语音房间的提示更清楚
  • 在控制台的多人语音房间中，有人离开不再会结束其他人的连接。成员仍然固定：要换一组人继续通话，请离开并新建一个房间。
  • 连接到已满的房间，或者达到所在环境的实时通信上限时，多人语音房间会说明原因和处理方法。
  • 加入一个不是为三人或四人创建的房间时，会被拒绝，并显示专门的提示。
2026-10-26：参考文档提供中文和日文版
  • 参考目录、JavaScript SDK和ESP32 SDK的参考文档，以及SDK能力与兼容性页面，现已提供中文和日文版。来自API定义的说明暂时仍为英文。
  • 参考文档现在只介绍你可以使用的内容。ESP32 SDK缺少的RTC功能显示为“ESP32暂不支持”。
  • 本更新日志只列出开发者能感知到的变更。
2026-10-25：多人语音房间指南
  • 新指南：多人语音房间介绍三到四个人如何用公开API和JavaScript SDK，从浏览器加入同一个语音房间：创建或加入房间、连接、发布、读取成员列表、收听和离开，每个会改变状态的步骤都需要用户同意。指南也说明了预览版的限制。
2026-10-25：JavaScript快速入门加入OneSay Agent；新增MCP指南和设备诊断
  • JavaScript快速入门介绍如何在你的房间中用client.rtc.agents.create启动OneSay Agent，用client.rtc.agents.get读取它，用client.rtc.agents.stop结束它。创建、更改或结束某项内容的调用需要你在OneSay中确认：确认之前，服务端返回consent_required；确认后，用同一个幂等键重试。
  • 新增指南：面向AI客户端的MCP指南，以及设备诊断。
  • MCP服务器提供17个工具、4个资源和2个提示词。R0工具无需账号；R1工具读取你的账号有权读取的内容；R2工具会更改内容，需要你在OneSay中确认。MCP服务器已在Staging上运行，生产环境尚未提供。
2026-10-24：控制台新增语音通话试用
  • 控制台新增语音通话试用：在浏览器中与OneSay Agent对话，从创建房间到关闭房间逐步进行。每个创建、更改或结束某项内容的步骤都会先请你确认。仅限Staging。
  • JavaScript SDK：RealtimeClient自行处理它自己的心跳回复，把其余每个pong都交给你的应用，包括心跳ping收到error作为回复的情况。
2026-10-23：开发者中心支持三种语言
  • 开发者中心、文档和控制台提供English、中文和日本語三种语言。切换语言后仍停留在同一页面。
2026-10-22：服务地址改用onesay.com
  • Control API：https://api.onesay.com/v1（Staging：https://api.staging.onesay.com/v1）。
  • 语音任务使用的Realtime WebSocket：wss://realtime.onesay.com/v1（Staging：wss://realtime.staging.onesay.com/v1）。
  • MCP：https://mcp.onesay.com/mcp（Staging：https://mcp.staging.onesay.com/mcp）。
  • SDK的环境表使用这些地址。
2026-10-20：RTC连接和SDK能力矩阵
  • 对仍在准备中的房间调用POST /v1/rtc/connections，会返回202和retry_after_ms。过了这段时间后，用新的Idempotency-Key再次请求；房间就绪后返回201。JavaScript SDK的rtc.connect会替你等待并重试。
  • SDK能力与兼容性页面列出每个SDK支持的内容。
  • ESP32：onesay_esp32_rtc_prepare会在发出任何请求之前拒绝任何已选择的media_encryption，返回ONESAY_ERR_INVALID_ARG；请不要设置这个字段。
2026-10-17：语音任务和RTC共用一个房间
  • 用POST /v1/rooms创建的房间可以同时用于语音任务和RTC。POST /v1/rooms/{room_id}/close会同时结束两者：连接关闭，SDK会话报告closed。已关闭的房间无法加入，也无法重新打开。
  • 实时连接可以请求context_snapshot.read授权，这样在该连接上创建的任务就可以携带ContextSnapshot。如果听写任务的ContextSnapshot无法使用，任务在创建时就会以task_profile_input_unsupported被拒绝。
  • ESP32 RPC：SDK可以响应RPC调用，并只回复原调用方；暂不能发起RPC调用。
2026-10-15：JavaScript支持端到端加密的RTC音频
  • rtc.connect({ mediaEncryption: "e2ee" })使用服务端签发、每30秒轮换一次的参与者专属密钥，对音频帧进行端到端加密。无法运行加密的浏览器会在加入之前失败，从不以未加密的方式加入。session.capabilities.e2ee只在这种模式下为true。密钥由OneSay签发，因此OneSay能够解密音频。
  • 新增错误码resource_busy：麦克风被其他采集占用时，JavaScript SDK会在publishMicrophone中抛出它。在ESP32上，你的采集和播放回调可以返回ONESAY_ERR_RESOURCE_BUSY，由onesay_esp32_rtc_read_media_status报告。
2026-10-14：控制台的资源视图
  • 控制台可以查看资源详情、带请求时间线的请求诊断、按维度划分的用量，以及Agent详情，并可在确认后停止Agent。
  • 控制台可以创建资源并更新元数据，创建和轮换API密钥（轮换会立即撤销之前的密钥），创建设备及其激活码，以及轮换设备凭据，每项操作都会先让你检查更改。返回的密钥默认隐藏，需要你手动显示；切换范围或离开页面时会被清除。
查看原始Markdown
# 更新日志



## 2026-10-27：多人语音房间和OneSay Agent更稳定

- 多人语音房间：修复了在其他人已经在说话的房间中加入和收听时的问题。服务器繁忙时，控制台会自动重试这一步，最多3次，并显示正在重试。
- 多人语音房间：只提供你自己的麦克风音频源，不再列出同一环境中其他人的音频源。
- OneSay Agent对话不再在约38秒后结束。
- 停止Agent后，一旦停止得到确认，读取Agent运行会返回`stopped`和`effective_stopped_at`，不再一直停留在`pending`。控制台会替你读回。
- 关闭房间时如果遇到服务重启，会自动重试，已关闭的房间不再一直占用环境的活跃房间名额。

## 2026-10-27：文档和控制台更易读

- 比屏幕宽的文档表格，会在还能滚动的一侧显示渐隐效果，适用于文档、示例、本更新日志和社区页面。表格中的标识符不再从名称中间断行。
- 在窄屏上，标题的`#`链接与标题保持在同一行，面包屑不再在行尾留下分隔符，上一篇和下一篇链接的“上一篇”“下一篇”单独显示在页面标题上方。
- 控制台的各个视图改为标签页：用方向键在标签之间移动，按Enter打开。
- 开发者中心、文档和控制台的中文和日文文本已重新检查，日文现在遵循统一的风格指南和术语表。

## 2026-10-26：多人语音房间的提示更清楚

- 在控制台的多人语音房间中，有人离开不再会结束其他人的连接。成员仍然固定：要换一组人继续通话，请离开并新建一个房间。
- 连接到已满的房间，或者达到所在环境的实时通信上限时，多人语音房间会说明原因和处理方法。
- 加入一个不是为三人或四人创建的房间时，会被拒绝，并显示专门的提示。

## 2026-10-26：参考文档提供中文和日文版

- [参考目录](../reference/generated/catalog.md)、[JavaScript SDK](../reference/generated/javascript-sdk-draft.md)和[ESP32 SDK](../reference/generated/esp32-sdk.md)的参考文档，以及[SDK能力与兼容性](../reference/generated/sdk-compatibility.md)页面，现已提供中文和日文版。来自API定义的说明暂时仍为英文。
- 参考文档现在只介绍你可以使用的内容。ESP32 SDK缺少的RTC功能显示为“ESP32暂不支持”。
- 本更新日志只列出开发者能感知到的变更。

## 2026-10-25：多人语音房间指南

- 新指南：[多人语音房间](../guides/MULTI_PARTY_VOICE_ROOM.md)介绍三到四个人如何用公开API和JavaScript SDK，从浏览器加入同一个语音房间：创建或加入房间、连接、发布、读取成员列表、收听和离开，每个会改变状态的步骤都需要用户同意。指南也说明了预览版的限制。

## 2026-10-25：JavaScript快速入门加入OneSay Agent；新增MCP指南和设备诊断

- [JavaScript快速入门](../guides/JAVASCRIPT_QUICKSTART.md)介绍如何在你的房间中用`client.rtc.agents.create`启动OneSay Agent，用`client.rtc.agents.get`读取它，用`client.rtc.agents.stop`结束它。创建、更改或结束某项内容的调用需要你在OneSay中确认：确认之前，服务端返回`consent_required`；确认后，用同一个幂等键重试。
- 新增指南：面向AI客户端的[MCP指南](../guides/MCP_GUIDE.md)，以及[设备诊断](../guides/DEVICE_DIAGNOSTICS.md)。
- MCP服务器提供17个工具、4个资源和2个提示词。R0工具无需账号；R1工具读取你的账号有权读取的内容；R2工具会更改内容，需要你在OneSay中确认。MCP服务器已在Staging上运行，生产环境尚未提供。

## 2026-10-24：控制台新增语音通话试用

- [控制台](CONSOLE.md)新增语音通话试用：在浏览器中与OneSay Agent对话，从创建房间到关闭房间逐步进行。每个创建、更改或结束某项内容的步骤都会先请你确认。仅限Staging。
- JavaScript SDK：`RealtimeClient`自行处理它自己的心跳回复，把其余每个`pong`都交给你的应用，包括心跳ping收到`error`作为回复的情况。

## 2026-10-23：开发者中心支持三种语言

- 开发者中心、文档和控制台提供English、中文和日本語三种语言。切换语言后仍停留在同一页面。

## 2026-10-22：服务地址改用onesay.com

- Control API：`https://api.onesay.com/v1`（Staging：`https://api.staging.onesay.com/v1`）。
- 语音任务使用的Realtime WebSocket：`wss://realtime.onesay.com/v1`（Staging：`wss://realtime.staging.onesay.com/v1`）。
- MCP：`https://mcp.onesay.com/mcp`（Staging：`https://mcp.staging.onesay.com/mcp`）。
- SDK的环境表使用这些地址。

## 2026-10-20：RTC连接和SDK能力矩阵

- 对仍在准备中的房间调用`POST /v1/rtc/connections`，会返回`202`和`retry_after_ms`。过了这段时间后，用新的`Idempotency-Key`再次请求；房间就绪后返回`201`。JavaScript SDK的`rtc.connect`会替你等待并重试。
- [SDK能力与兼容性](../reference/generated/sdk-compatibility.md)页面列出每个SDK支持的内容。
- ESP32：`onesay_esp32_rtc_prepare`会在发出任何请求之前拒绝任何已选择的`media_encryption`，返回`ONESAY_ERR_INVALID_ARG`；请不要设置这个字段。

## 2026-10-17：语音任务和RTC共用一个房间

- 用`POST /v1/rooms`创建的房间可以同时用于语音任务和RTC。`POST /v1/rooms/{room_id}/close`会同时结束两者：连接关闭，SDK会话报告`closed`。已关闭的房间无法加入，也无法重新打开。
- 实时连接可以请求`context_snapshot.read`授权，这样在该连接上创建的任务就可以携带ContextSnapshot。如果听写任务的ContextSnapshot无法使用，任务在创建时就会以`task_profile_input_unsupported`被拒绝。
- ESP32 RPC：SDK可以响应RPC调用，并只回复原调用方；暂不能发起RPC调用。

## 2026-10-15：JavaScript支持端到端加密的RTC音频

- `rtc.connect({ mediaEncryption: "e2ee" })`使用服务端签发、每30秒轮换一次的参与者专属密钥，对音频帧进行端到端加密。无法运行加密的浏览器会在加入之前失败，从不以未加密的方式加入。`session.capabilities.e2ee`只在这种模式下为true。密钥由OneSay签发，因此OneSay能够解密音频。
- 新增错误码`resource_busy`：麦克风被其他采集占用时，JavaScript SDK会在`publishMicrophone`中抛出它。在ESP32上，你的采集和播放回调可以返回`ONESAY_ERR_RESOURCE_BUSY`，由`onesay_esp32_rtc_read_media_status`报告。

## 2026-10-14：控制台的资源视图

- 控制台可以查看资源详情、带请求时间线的请求诊断、按维度划分的用量，以及Agent详情，并可在确认后停止Agent。
- 控制台可以创建资源并更新元数据，创建和轮换API密钥（轮换会立即撤销之前的密钥），创建设备及其激活码，以及轮换设备凭据，每项操作都会先让你检查更改。返回的密钥默认隐藏，需要你手动显示；切换范围或离开页面时会被清除。