第三方 API：RTC 接入

RTC 有两种凭据，不能混用：业务后端用 ak_pat_ 管房间和签发一次性入会票据；参会设备用 RTC Token 加入、发布、订阅和播放。浏览器不需要 AKStream.Next 账号密码。

sequenceDiagram
    participant Backend as 第三方业务后端
    participant API as AKStream.Next
    participant Client as RTC 浏览器或 App
    participant Media as MediaServer
    Backend->>API: API Token 创建房间
    Backend->>API: 为业务 subject 签发一次性 access ticket
    API-->>Backend: accessTicket
    Backend-->>Client: 只发送 accessTicket
    Client->>API: v2 票据入会接口 消费一次性票据
    API-->>Client: RTC Token + 设备会话 + 能力
    Client->>API: X-AK-RTC-Token + WHIP/WHEP
    API->>Media: 代理 SDP 和媒体会话

后端签发一次性入会票据

业务后端先创建或选择房间，然后按自己的用户 ID 签发票据：

POST /api/v2/rtc/rooms/{roomId}/access-tickets
Authorization: Bearer ak_pat_<TOKEN>
Content-Type: application/json

{
  "subjectIssuer": "dispatch-system",
  "subjectId": "user-1001",
  "displayName": "调度员一号",
  "role": "speaker",
  "capabilities": ["camera.publish", "microphone.publish", "publications.subscribe", "chat.send"],
  "expiresInMinutes": 10,
  "bypassWaitingRoom": false
}

subjectIssuer + subjectId 是第三方业务主体的稳定身份。完整 accessTicket 只返回一次、只能消费一次，并且不能调用平台管理 API。不要把 API Token 发送给参会端。

参会端加入并续签

客户端使用一次性票据加入：

POST /api/v2/rtc/session/rooms/{roomId}/join
Content-Type: application/json

{
  "accessTicket": "<一次性票据>",
  "displayName": "调度员一号",
  "platform": "pc-web",
  "clientVersion": "2.4.0",
  "micEnabled": true,
  "cameraEnabled": true
}

响应返回 participantToken、expiresAt、成员、设备会话、最终能力和等候室状态。后续请求使用：

X-AK-RTC-Token: <participantToken>

在过期前调用 POST /api/v2/rtc/session/rooms/{roomId}/token/refresh。续签会轮换 tokenVersion，旧 RTC Token 立即失效。设备定期发送 heartbeat；离会调用 /leave，不能只关闭浏览器标签页。

发布、订阅和活动播放

RTC 是 SFU：每个 Publication 独立发布，每个 Subscription 独立订阅，不是服务端自动混成一个画面。

任务	接口	关键点
创建发布	`POST /api/v2/rtc/session/rooms/{roomId}/publications`	服务端按角色和房间策略过滤媒体能力
WHIP 发布	`POST /api/v2/rtc/session/rooms/{roomId}/publications/{publicationId}/whip`	请求/响应是 SDP，不是 JSON
查询发布	`GET /api/v2/rtc/session/rooms/{roomId}/publications`	只订阅 Active 且允许的发布
创建订阅	`POST /api/v2/rtc/session/rooms/{roomId}/subscriptions`	绑定当前观看设备和目标 Publication
WHEP 播放	`POST /api/v2/rtc/session/rooms/{roomId}/subscriptions/{subscriptionId}/whep`	保存返回的媒体会话和释放地址
HTTP-FLV 播放	`POST /api/v2/rtc/session/rooms/{roomId}/playback-ticket`	返回绑定房间、设备和活动 Publication 的短时地址

RTC Token 只能用于绑定房间和设备。活动播放票据只能看同一房间的活动 Publication，不能替代 RTC Token、发布票据或平台 API Token。

会议录制和归档

1.0.0.157 以逐发布的旧录像控制为主；1.0.0.158 已新增整场持续录制。旧接口仍可用，但它的 recording/targets、recording/start、recording/stop 不能代替持续任务的 recordingId。

会议结束后查询：

GET /api/v2/rtc/session/rooms/{roomId}/playback/manifest
X-AK-RTC-Token: <participantToken>

1.0.0.158 按 roomId + recordingId 管理持续录制档案。业务后端先用 POST /api/v2/rtc/rooms/{roomId}/recordings/access 按 view/play/download 签短时票据，再用 GET /api/v2/rtc/recordings?roomId=... 找任务、读取该任务的 manifest 与受控媒体资源。任务可包含成员/屏幕兼容副本、聊天、白板、发言与主持事件；还可按需生成整场 MP4。会中入会 Token 不等于会后档案票据，旧任务缺失的媒体或事件不能补造。精确入参、出参和错误见RTC 档案 API，客户端接入见RTC SDK 录制与回放。

失败处理

现象	先检查什么
join 返回票据无效	access ticket 是否过期、已消费、被撤销或 roomId 不匹配
返回 Waiting	等候室是否启用，主持人是否已准入
RTC Token 401	令牌是否过期、设备会话是否撤销、tokenVersion 是否已轮换
WHIP/WHEP 成功但无媒体	ICE candidate、TURN、UDP/TCP、防火墙、浏览器权限和 codec
HTTP-FLV 被拒绝	是否使用当前 RTC Token 重新签发 playback-ticket，Publication 是否仍 Active
录制列表为空	房间是否允许录制、Publication 是否可录、是否等待分片封口和索引

RTC 生产验收必须使用真实 Chrome/Edge/Safari/Firefox、摄像头和麦克风，验证弱网、断线重连、TURN、屏幕共享和长时间运行。自动 SDP 测试不能代替真人音视频验收。