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

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

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 方法，不要自行重写 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。内部组件接口不属于第三方业务入口；较新文档不代表旧部署已具备能力。

完整 Skill 文件目录