第三方 API：5 分钟跑通

这套接口专门给业务后端调用。不要登录页面取 Cookie，也不要把长期 API Token 发给浏览器、App 安装包或播放器。

你只需要准备两项：AKStream.Next 的 HTTPS 地址，以及管理员分配的 ak_pat_ API Token。

sequenceDiagram
    participant Backend as 第三方业务后端
    participant API as AKStream.Next API
    participant Media as MediaServer
    participant Player as 浏览器或播放器
    Backend->>API: Bearer API Token 查询资源
    Backend->>API: 申请目标资源短时地址
    API-->>Backend: 带 ak_ticket 的播放地址
    Backend-->>Player: 只返回短时地址
    Player->>Media: 播放 HLS/FLV/fMP4
    Media->>API: OnPlay 校验票据和资源
    API-->>Media: 允许或拒绝

第一步：验证 Token

export AK_BASE='https://ak.example.com'
export AK_TOKEN='ak_pat_<完整令牌>'

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H 'Accept: application/json' \
  "$AK_BASE/api/v2/third-party/capabilities"

成功响应会列出 Token 当前实际拥有的权限和可用能力分类。这里返回 401，说明 Token 无效、已过期、已吊销、来源 IP 不在白名单，或者你误用了页面登录令牌。

第二步：查询通道并播放

先查通道：

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $AK_TOKEN" \
  "$AK_BASE/api/v2/third-party/channels?page=1&pageSize=50"

如果通道没有在线，且 Token 有 channels.manage，启动普通 RTSP/ONVIF 通道：

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $AK_TOKEN" \
  "$AK_BASE/api/v2/third-party/channels/camera-001/start"

启动成功只表示命令已受理。继续查询 /api/v2/third-party/streams，等 state 变成 Online，再创建 URL 不变的播放租约：

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"protocols":["http-flv","http-fmp4","hls"],"leaseSeconds":120,"absoluteLifetimeSeconds":43200}' \
  "$AK_BASE/api/v2/third-party/channels/camera-001/playback-lease"

响应中的 sources[].url 可以直接交给当前用户的播放器。到 renewAfter 时只续租，不更换 URL：

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"leaseSeconds":120}' \
  "$AK_BASE/api/v2/third-party/playback-leases/<leaseId>/renew"

续租响应只更新时间，播放器不需要重设 source。达到 absoluteExpiresAt、租约已经过期/撤销，或原 API Token 失效后，应创建新租约。原 /playback 一次性短地址仍保留给不需要续租的简单场景。

第三步：按用途申请权限

业务用途	建议最小权限
只同步通道和状态	`channels.view`、`streams.view`
播放已经在线的直播	再加 `streams.play`
启动、停止普通通道	再加 `channels.manage`
查询录像并播放	`recordings.view`、`recordings.play`
下载录像	再加 `recordings.download`
裁剪合并、恢复软删	再加 `recordings.manage`
软删、硬删录像或删除裁剪结果	再加 `recordings.delete`
GB28181 点播和 PTZ	`devices.view`、`devices.control`
创建 RTC 房间并签发入会票据	`rtc.manage`
配置第三方 Webhook	只读 `system.view`；管理 `system.config.manage`

不要为了省事给普通集成分配 *。每套业务系统使用独立 Token，写清用途、负责人、有效期和允许 IP；轮换时先部署新 Token，再吊销旧 Token。

接下来按任务看

直播播放：普通通道、GB28181、HLS、HTTP-FLV、HTTP-fMP4 和票据续签。
录像与裁剪删除：查询、播放、下载、裁剪合并、软删、恢复和硬删。
RTC 接入：业务主体票据、RTC Token、WHIP/WHEP、活动播放和会议归档。
第三方 API 分类速查：逐条接口、权限、主要输入和完成判断。
GB28181 接口 / ONVIF 接口：设备发现、目录、PTZ、预置位、截图 URI、告警和对讲。
异步命令与事件 / 第三方 Webhook：终态等待、事件去重、签名、重试和回放。
OpenAPI、Postman 与 SDK：按发布版本获取精确字段、模型和可导入联调资产。

所有非 2xx 响应都要保存 HTTP 状态、code、message 和 traceId。不要记录完整 Token 或带 ak_ticket 的 URL。