# 第三方 API：RTC 接入

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

```mermaid
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 签发票据：

```http
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 发送给参会端。

## 参会端加入并续签

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

```http
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`、成员、设备会话、最终能力和等候室状态。后续请求使用：

```http
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`。

会议结束后查询：

```http
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](api-rtc-archive.md)，客户端接入见[RTC SDK 录制与回放](../sdk/recording.md)。

## 失败处理

| 现象 | 先检查什么 |
|---|---|
| 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 测试不能代替真人音视频验收。