# 第三方 API：5 分钟跑通

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

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

```mermaid
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

```bash
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 不在白名单，或者你误用了页面登录令牌。

## 第二步：查询通道并播放

先查通道：

```bash
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 通道：

```bash
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 不变的播放租约：

```bash
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：

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

## 接下来按任务看

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

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