# RTC API 对接：建会、入会、媒体与会议控制

本页以实际发布的 **1.0.0.158** 服务端接口为准，给业务后端和 SDK 接入者分清“谁调用什么”。业务后端用具备相应权限的 `Authorization: Bearer ak_pat_...` 管理会议并签一次性票据；参会 SDK 消费票据后，用设备绑定的 `X-AK-RTC-Token` 调用 `/api/v2/rtc/session/...`。浏览器和 App 不应持有平台管理 Token。录制档案另用[档案 API](api-rtc-archive.md)的短时票据。

```mermaid
sequenceDiagram
    participant Business as 业务后端
    participant API as AKStream.Next
    participant SDK as 参会 SDK
    Business->>API: POST /rtc/rooms（ak_pat_）
    Business->>API: POST /rooms/{roomId}/access-tickets
    Business-->>SDK: roomId + 一次性 accessTicket
    SDK->>API: POST /session/rooms/{roomId}/join
    API-->>SDK: participantToken + deviceSessionId + capabilities
    SDK->>API: X-AK-RTC-Token + 独立发布/订阅/信令
```

## 业务后端：房间和一次性身份

| 接口 | 用途与入参 | 返回/下一步 | 权限与特殊情况 |
|---|---|---|---|
| `GET /api/v2/rtc/capabilities` | 查此服务的 SFU 能力 | 功能/媒体能力 | 先确认实际部署版本；不能把规划能力当真机已支持。 |
| `GET /api/v2/rtc/rooms`、`GET /api/v2/rtc/rooms/{roomId}` | 按状态/会议号查列表与详情 | 房间策略、状态、人数 | 业务查询按当前授权过滤；已关闭房间不再接受新设备。 |
| `POST /api/v2/rtc/rooms` | `CreateRtcRoomRequest`：`name`、`roomType`、`mediaServerId`、`maxParticipants`、`accessMode`、`waitingRoomEnabled`、录制/白板/聊天开关等 | 房间结果中的 `roomId` | `rtc.manage`；`idempotencyKey` 可选 UUID，同一组织者同一请求失败重试应复用。设置 `enableRecording=true` **不自动开录**。 |
| `POST /api/v2/rtc/rooms/{roomId}/access-tickets` | `subjectIssuer`、`subjectId`、`displayName`、`role`、`capabilities`、`expiresInMinutes`、`bypassWaitingRoom` | 一次性 `accessTicket`、会议与到期信息 | `rtc.manage`；业务主体由你的系统定义，不在平台创建用户密码。票据只能消费一次、明文只返回一次。 |
| `PUT /api/v2/rtc/rooms/{roomId}/capacity` | 成员/发布等上限 | 更新后房间策略 | 新上限不能绕开授权配额，服务端核对现有占用。 |
| `POST /api/v2/rtc/rooms/{roomId}/close` | 管理端结束会议 | 关闭状态及成员离线 | `rtc.manage`；当前设备会话和媒体陆续释放，不是简单隐藏页面。 |

主要建会字段：`roomType` 可为 `meeting/chatroom/screen/whiteboard`；`accessMode` 为 `Open/InviteOnly`；`passcode` 是可选口令，服务端只存摘要；`scheduledStartAtUtc` 配合 `durationMinutes` 可预约，`earlyJoinMinutes/maxExtensionMinutes/reminderMinutes` 控制时间边界；`maxPublishers/maxScreenShares` 是房间级限制，授权额度仍独立生效。`mediaServerId/app` 决定目标媒体节点与命名空间，不能从客户端随意改写。

入会票据字段：`subjectIssuer + subjectId` 是稳定业务身份；`displayName` 由后端确认；`capabilities` 是允许授予的上限，实际能力还要与角色和房间策略取交集；`bypassWaitingRoom` 只有有权签票的业务方可使用。不要把 `accessTicket` 放在可分享的网页 URL、日志或数据库明文列。

## 参会 SDK：设备会话与续签

| 接口 | 主要入参 | 返回/下一步 | 规则 |
|---|---|---|---|
| `POST /api/v2/rtc/session/rooms/{roomId}/join` | JSON `accessTicket`、可选 `passcode`、`platform`、`clientVersion`、初始 `micEnabled/cameraEnabled` | `participantToken`、到期时间、成员/设备会话、最终能力、`admissionStatus` | 唯一无需既有 RTC Token 的参会动作；`Waiting` 不允许提前发布。 |
| `POST /api/v2/rtc/session/rooms/{roomId}/token/refresh` | 当前设备 `X-AK-RTC-Token` | 新 Token 与版本/到期时间 | 轮换后旧 Token 失效；SDK 在到期前自动续签，失败时不无限重放旧票。 |
| `GET /api/v2/rtc/session/rooms/{roomId}`、`GET .../participants` | 当前设备令牌 | 房间、成员、策略、能力快照 | 仅当前会议可见；离会/换机后旧设备身份不得继续使用。 |
| `GET .../admission/status` | 当前设备令牌 | `Waiting/Admitted/Denied` | 等候室须由主持审批；被拒绝后向业务后端重新取得资格。 |
| `POST .../heartbeat` | 当前设备令牌 | 保活状态 | 服务端核对设备绑定；浏览器/原生 SDK 已定时发送。 |
| `POST .../leave` | 当前设备令牌 | 离会结果 | 主动释放设备会话、发布和订阅；只关浏览器标签页要等超时治理。 |
| `GET .../connection-settings` | 当前设备令牌 | STUN/TURN 配置 | SDK 使用服务端当时的候选，不把 TURN 密码写入 App 包。 |
| `GET .../signaling/ws?lastSequence=N` | 当前设备令牌、补偿游标 | WebSocket 事件流 | 重连按序号补偿；撤销/踢出事件不得从旧会话重放到新设备。 |

`platform` 允许 `pc-web/h5/android/ios/wechat-mini-program` 等实际端标识。设备会话 ID 是一次入会身份，**不是硬件序列号**。请求声明 `capabilities` 或开启初始媒体不等于获得能力；以后所有 HTTP/WS 请求均按服务端最终能力和当前房间状态检查。

## 独立媒体发布与订阅

| 任务 / 接口 | 入参 | 返回与完成条件 | 特殊情况 |
|---|---|---|---|
| `POST .../publications` | `mediaKind`=`MicrophoneAudio/CameraVideo/ScreenVideo/ScreenAudio`（小程序可用 `MiniProgramCombined`），可选 `codec/simulcast/layers` | `publicationId` 等待协商 | 一个成员可有多路；`codec` 是期望，最终以 SDP 和媒体节点协商为准。 |
| `POST .../publications/{publicationId}/whip` | `Content-Type: application/sdp` 的 offer | SDP answer、媒体会话/释放地址 | 不是 JSON；只有拥有该 Publication 的设备可发，同时受当前实例可用额度限制。 |
| `GET .../publications` | 当前设备令牌 | 可见、可订阅的发布列表 | 摄像头、麦克风与共享屏幕各有独立 ID；不要按成员名合并。 |
| `POST .../subscriptions` | `publicationId`，可选 `priority(-100..100)`、`requestedLayer`、`visible/pinned` | `subscriptionId` | 只订阅获准且活动的 Publication。 |
| `POST .../subscriptions/{subscriptionId}/whep` | `application/sdp` offer | SDP answer 与媒体会话 | 保存并在离会/停止订阅时释放；本机画面不证明远端解码成功。 |
| `POST .../subscriptions/{subscriptionId}/stop`、`POST .../publications/{publicationId}/stop` | 各自 ID | 停止状态 | 只能停止当前设备拥有的媒体；不得拿别人的 ID 操作。 |
| `POST .../playback-ticket` | 当前会议、活动发布 | 短时 HTTP-FLV 播放地址 | 与入会/管理/会后档案票据不同；目标发布停止即失效。 |

上述省略号 `...` 均指 `/api/v2/rtc/session/rooms/{roomId}`。SDK 已处理 SDP、ICE、会话恢复与资源释放；业务页面应调用[SDK 方法](../sdk/web-api.md)，不要自行重写 WHIP/WHEP。HTTP `200` 仅说明控制面协商成功，仍须在第二台设备核对真实视频帧和音频包。

## 主持治理、外部源和协作

| 接口组 | 用途 / 关键参数 | 权限与边界 |
|---|---|---|
| `PUT .../access-policy`、`POST .../participants/{participantId}/admission` | 改 `accessMode/waitingRoomEnabled/isLocked`；按 `admit` 审批等候者 | 当前获准主持/治理者；角色在执行时重新检查。 |
| `POST .../host/transfer`、`POST .../host/claim`、`POST .../participants/{participantId}/cohost` | 移交、无人主持时接管、联席主持任免 | 移交后旧主持的专属操作立刻失效；`claim` 不可抢占有效主持。 |
| `POST .../participants/{participantId}/moderation`、`PUT .../video-quality` | 静音/关视频/踢出/角色，或指定成员质量目标 | 操作者和目标成员身份受服务端核验；质量目标不是实时达到值。 |
| `POST .../invitations`、`GET .../invitations`、`POST .../invitations/{invitationId}/revoke` | 主持签发、查看和撤销邀请 | 邀请只在有效期且未消费/撤销时能入会。 |
| `POST .../whiteboard/access-request`、`POST .../participants/{participantId}/whiteboard-access`、`POST .../whiteboard/lock` | 申请、审批/收回、锁定协作白板 | 上传素材最后提交时仍重查书写权；锁定不删除旧事件。 |
| `POST .../chat/attachments`、`GET .../chat/attachments/{attachmentId}` | 上传/读取聊天或白板素材 | 私发可见性和设备身份都在读取、提交时检查。 |
| `GET .../external-sources/candidates`、`GET .../external-sources`、`POST .../external-sources`、`DELETE .../external-sources/{bindingId}` | 候选授权、已入会源、按 `grantId` 加入、按 `bindingId` 移出 | 外部源不计真人，移出只影响本会议，不停止原通道。 |

外部源的**业务授权**先由管理 API `GET/POST /api/v2/rtc/rooms/{roomId}/external-sources/grants`、`DELETE .../grants/{grantId}` 按现有 `channelId` 建立/撤销。`GrantRtcExternalSourceRequest` 可设 `allowRecording/allowHistoricalArchive`；主持 SDK 只能选择已授权的 `grantId`。候选截图接口只返回授权源的最近图片，不公开 RTSP 源地址。GB28181、RTSP、H265/G711 等具体源仍要在目标环境验证编码与权限。

## 常见错误和下一步

| 状态/现象 | 含义与处理 |
|---|---|
| 400 | 请求字段、SDP、能力或范围无效；先按本版模型检查字段和 `Content-Type`。 |
| 401 | 一次性票据无效/已消费、RTC Token 过期或旧设备被替换；向业务后端取新票，不循环旧票。 |
| 403 | 当前会议、角色、设备或授权范围不允许；隐藏按钮不是权限实现。 |
| 404 | 房间、成员、Publication/Subscription、授权源不存在或不属于本会。 |
| 409 / 等待状态 | 会议容量、主持移交、旧媒体会话等状态冲突；查询当前快照后按服务端允许的路径恢复。 |
| 本机有预览、对方无画面 | 检查 WHIP/ICE/TURN、授权流额度、Publication 实际状态和远端解码。 |

完整公开 HTTP 方法、路径和模型见同版 Skill 中的 `references/openapi.json`。内部组件接口不属于第三方业务入口；较新文档不代表旧部署已具备能力。