REST API 总览与调用约定

鉴权、信封、分页、错误、幂等、请求追踪与各产品端点索引（构建时从 openapi.json 生成）。

由公开 REST 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

本页是 REST API Reference 的入口。所有接口表都在构建时从公开 REST 接口定义生成：下面的产品分组、后续每个分组页里的方法/路径/参数/请求体/响应/curl，都由脚本读接口定义直接渲染，不存在手抄的接口清单。

调用前提与请求示例#

• 基址：https://api.your-domain.example（占位符，替换为你的控制面地址）。
• 鉴权：服务端调用使用 Authorization: Basic base64(customerId:customerSecret)；控制台调用使用 Authorization: Bearer <session>。
• 请求头：写操作必须带 Content-Type: application/json；建议带 X-Request-Id 便于排障。
• 响应：成功返回资源对象；失败返回统一错误信封 { code, message, reason, sdkCode, details? }。

curl -s https://api.your-domain.example/v1/tokens \
  -u "$CUSTOMER_ID:$CUSTOMER_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"channelName":"weekly-sync","uid":10001,"role":"host","ttlSeconds":3600}'

什么时候用 REST、什么时候用 SDK#

权限与凭证边界#

每个分组页里有什么#

• 该分组的操作索引（方法 / 路径 / 摘要，可点击跳转）；
• 每个操作：参数表（名称/位置/必填/类型/约束）、请求体字段表 + 示例、响应表、可直接复制的 curl；
• 该分组用到的 components.schemas（字段表由接口定义展开）。

与其他页面的关系#

• 错误信封与错误码： 错误码全表（由 接口定义 生成）。
• 回调（Webhook）事件： 回调事件参考（由 接口定义 生成）。
• 端到端示例：见 快速开始 中的可运行脚本。

下一步#

• REST API 参考：完整端点、参数与 curl。
• 错误码：失败时按 code / HTTP 状态定位。
• 常见问题：配额、限制与排障。

鉴权

项目凭证（Basic）只应存在于服务端；浏览器/移动端只持有 { appId, rtcToken, rtcUid }。

通用约定

• 写操作（POST/PUT/PATCH）必须带 Content-Type: application/json，否则返回 415 unsupported_media_type。
• 列表分页使用 page_no（0 起）与 page_size（1..500，默认 100）。
• 失败响应用统一信封 { code, message, reason, sdkCode, details? }，完整错误码见 错误码。
• 每个响应都回显 X-Request-Id，排障时优先提供它。
• 声网兼容路径以 /dev/v1/*、/v1/apps/{appid}/cloud_recording/*、/v1/projects/{appid}/fls/* 为前缀，响应使用声网的 success/data、{resourceId,sid,serverResponse} 等信封。
• 幂等：创建类接口重复提交可能返回同一资源；写操作失败后先查询再重试（见 错误码 的 409 说明）。

产品分组与操作索引

共 189 个操作，分 15 个产品分组，每个分组一个独立页面：

Schema 字典

components.schemas 声明与引用统计：

• 被操作引用：68
• 声明总数（含别名）：58

各分组页面内也会展开该分组用到的 schema。