OneSay开发者

搜索文档目录

本页内容

OneSay文档

文档

文档

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

PDF由浏览器的打印对话框生成，不是托管的导出服务。

这些指南说明客户端如何使用OneSay Control API、语音任务、实时语音（RTC），以及房间、音频源、SignalStream、任务和产物这些资源。指南和生成的参考文档不一致时，以参考文档为准。JavaScript SDK和ESP32 SDK都尚未发布到软件包仓库。

快速入门#

  • JavaScript快速入门：用已安装的软件包运行语音任务（输入你提供的音频，通过OneSay Realtime WebSocket获得任务结果）和RTC（发布、订阅、数据、RPC和显式启动的Agent）。
  • ESP32快速入门：从ESP-IDF应用运行语音任务，以及使用RTC组件。它介绍如何构建应用，不涉及烧录和激活开发板。
  • 多人语音房间：三到四个人从浏览器加入同一个语音房间，使用JavaScript SDK的分步说明，以及预览版当前的限制。

SDK参考#

  • API参考：Control API的每个操作及其请求和响应字段、示例和错误。
  • JavaScript SDK参考：环境、任务和RTC的入口、会话状态，以及声明的能力。
  • ESP32 SDK参考：组件、任务和RTC的入口，以及声明的能力及其限制。
  • SDK能力与兼容性：两个SDK的支持矩阵、不支持和未公开的条目、RTC生命周期、任务恢复、限制与隐私。
  • 官方参考：公开的API操作、事件、授权和错误。

AI客户端与诊断#

  • MCP指南：供AI客户端使用的OneSay MCP服务器，包括登录、工具、资源和提示词。
  • 设备诊断：设备的状态，以及它所属项目环境的脱敏日志。

安全与身份#

  • 凭据安全：浏览器、服务器和设备各自的边界。
  • 身份验证：用户通过授权码和PKCE登录，服务器使用绑定环境的API密钥或服务主体Token，设备使用各自的设备专属凭据。
  • API密钥：前缀表明密钥属于哪里（Staging为osp_stg_，生产环境的Test和Live分别为osp_test_和osp_live_）；前缀只是提示，不代表权限。密钥只显示一次，每次请求都会检查它是否已撤销。
  • 设备激活：先使用5分钟内有效的一次性激活码，再由设备用设备专属密钥换取短期访问Token。Realtime使用另外的60秒一次性连接票据。
  • 授权：每个资源属于哪个项目和环境，由服务端决定。授权必须显式授予，拒绝始终优先；凭据的权限范围只能缩小授权，不能扩大授权。
查看原始Markdown
# 文档

这些指南说明客户端如何使用OneSay Control API、语音任务、实时语音（RTC），以及房间、音频源、SignalStream、任务和产物这些资源。指南和生成的参考文档不一致时，以参考文档为准。JavaScript SDK和ESP32 SDK都尚未发布到软件包仓库。

## 快速入门

- [JavaScript快速入门](JAVASCRIPT_QUICKSTART.md)：用已安装的软件包运行语音任务（输入你提供的音频，通过OneSay Realtime WebSocket获得任务结果）和RTC（发布、订阅、数据、RPC和显式启动的Agent）。
- [ESP32快速入门](ESP32_QUICKSTART.md)：从ESP-IDF应用运行语音任务，以及使用RTC组件。它介绍如何构建应用，不涉及烧录和激活开发板。
- [多人语音房间](MULTI_PARTY_VOICE_ROOM.md)：三到四个人从浏览器加入同一个语音房间，使用JavaScript SDK的分步说明，以及预览版当前的限制。

## SDK参考

- [API参考](../reference/generated/public-api.md)：Control API的每个操作及其请求和响应字段、示例和错误。
- [JavaScript SDK参考](../reference/generated/javascript-sdk-draft.md)：环境、任务和RTC的入口、会话状态，以及声明的能力。
- [ESP32 SDK参考](../reference/generated/esp32-sdk.md)：组件、任务和RTC的入口，以及声明的能力及其限制。
- [SDK能力与兼容性](../reference/generated/sdk-compatibility.md)：两个SDK的支持矩阵、不支持和未公开的条目、RTC生命周期、任务恢复、限制与隐私。
- [官方参考](../reference/generated/catalog.md)：公开的API操作、事件、授权和错误。

## AI客户端与诊断

- [MCP指南](MCP_GUIDE.md)：供AI客户端使用的OneSay MCP服务器，包括登录、工具、资源和提示词。
- [设备诊断](DEVICE_DIAGNOSTICS.md)：设备的状态，以及它所属项目环境的脱敏日志。

## 安全与身份

- [凭据安全](CREDENTIAL_SAFETY.md)：浏览器、服务器和设备各自的边界。
- 身份验证：用户通过授权码和PKCE登录，服务器使用绑定环境的API密钥或服务主体Token，设备使用各自的设备专属凭据。
- API密钥：前缀表明密钥属于哪里（Staging为`osp_stg_`，生产环境的Test和Live分别为`osp_test_`和`osp_live_`）；前缀只是提示，不代表权限。密钥只显示一次，每次请求都会检查它是否已撤销。
- 设备激活：先使用5分钟内有效的一次性激活码，再由设备用设备专属密钥换取短期访问Token。Realtime使用另外的60秒一次性连接票据。
- 授权：每个资源属于哪个项目和环境，由服务端决定。授权必须显式授予，拒绝始终优先；凭据的权限范围只能缩小授权，不能扩大授权。