# API 开发规则

## 调用与认证

基础地址使用部署方提供的 HTTPS 地址。业务后端请求头为 `Authorization: Bearer ak_pat_<完整令牌>`；JSON 使用 UTF-8，SDP、文件、multipart 和 WebSocket 按契约处理。请求超时不代表未执行；写请求不无条件重放。保存状态码、Content-Type、code/errorCode、message、traceId 和服务端实际提供的 retryable；缺字段保持未知。

先调用 `/api/v2/third-party/capabilities` 确认有效权限，再读取 `/api/v2/security/permissions` 对应公开权限定义。便捷能力分类不代表通用管理 API 被禁用。准确权限在 `api-operations.md` 和 OpenAPI `x-akstream-permission`；还有资源/角色/配置约束时读取任务指南。`authenticated` 表示需有效身份；内部服务接口不会进入本契约，空权限不是生产安全豁免，`*` 表示该路由要求超级权限。

普通 API Token 不能读取在线 Swagger；使用离线 OpenAPI。浏览器不保存长期 Token，可由自己的后端转发获准的操作。修改公开 WebUI 时保留 Cookie/CSRF、登录刷新和结构化失败反馈；不能把后端 Token 塞入 WebUI 编译配置。

## 功能路线

下面的路径均相对于 `guides/`。先看任务，再查完整方法/路径，不从模块前缀猜请求。

| 功能与 WebUI 动作 | 任务指南 | 关键规则 |
|---|---|---|
| 总览、集群、节点、媒体服务、命令、性能状态 | development/local-run.md | 配置存在与进程在线分开；节点操作等终态 |
| 用户、角色、Token、RTSP 鉴权、审计、授权 | development/repository.md、development/api-security.md | 限权并处理实时收权；原 Token 仅后端保管 |
| 普通通道、分组、激活、流管理、资源迁移、对讲 | development/webui.md | 查询真实能力；稳定 channelId；停流会影响共享使用 |
| GB28181 注册、目录、点播、回放、PTZ、告警、级联 | development/add-module.md | SIP 受理与设备应答分开；PTZ 必须停止/超时释放 |
| ONVIF 发现、接入、Profile、PTZ、预置位、图像、事件 | development/testing-release.md | 先读取设备能力；不要假定全部设备支持 |
| 录像计划、手工录像、文件、裁剪合并、磁盘和保留 | development/database.md、development/third-party-recording.md | 逐项结果；软删/恢复/硬删分开；任务完成再签链接 |
| 周期截图、帧预览/下载、智能检索与索引任务 | development/webui.md、development/database.md | 截图票据绑定通道/当前源/动作；模型与索引能力以现场为准 |
| 显示墙、大屏节目、布局和播放状态 | development/webui.md | 保存节目与启动节目分开；客户端布局不等于服务端运行 |
| RTC 建会、票据、主持治理、协作、观察、外部流 | development/first-integration.md、development/api-rtc.md | 管理后端与参会 SDK 分开，观察和私发权限不扩大 |
| RTC 持续录制、时间线、合成、导出与档案授权 | development/api-rtc-archive.md、sdk/recording.md | 公共回放不包含定向私发；查看/播放/下载分别授权 |
| 配置中心、ZLM 参数、TLS、日志、后台任务、升级与生命周期 | development/local-run.md | 按管理权限调用；保存后核对运行生效/重启/回滚状态 |
| 直播、录像播放下载和稳定 URL 租约 | development/third-party-start.md、development/third-party-live.md、development/api-third-party-contract.md | 播放不暗中启动离线通道；续租保留 URL，不能超过绝对寿命 |
| 运行状态事件、协议事件与第三方 Webhook | development/async.md、operations/outbound-webhook.md | 按订阅协议鉴权/去重/补偿；不把 ZLM 入站 Webhook 当业务通知 |

这张表提供全功能检索路线；精确操作集合由随版 OpenAPI 决定。第三方可实现相同平台业务动作，也需遵守相同账号、权限、授权、节点和设备能力。登录、首次安装和会中设备授权仍采用对应专用流程。

## 首次安装和重新配置

先读取 `GET /api/v2/setup/status`。需要安装时，使用部署方在目标实例取得的安装码，在安装请求中发送 `X-AK-Setup-Token`；这不是 `ak_pat_` API Token。随版 OpenAPI 的 `x-akstream-availability: installation-only` 表示只在安装模式开放，安装完成后一般返回 404。

安装接口覆盖 catalog、文件目录的 roots/browse/directories/validate、database/test、detect/network、detect/nginx、notifications/test、media/build 的 inspect/status/start、preflight 和 complete。精确字段使用 OpenAPI 的 FirstRun 请求模型和 `guides/development/local-run.md`。先验证配置和预检，再按明确的安装任务提交 complete；不要为普通业务接入把已经安装的实例重置为安装模式。目录创建、媒体构建和最终安装会改变环境，不在普通连通性测试中自动执行。

## 一个真实直播闭环

业务后端调用 `GET /api/v2/third-party/channels?page=1&pageSize=50`，取 channelId。离线普通通道在具备 channels.manage 时 `POST /api/v2/third-party/channels/{channelId}/start`，保存命令标识，查询流到 Online；GB28181 的协议会话流程见国标指南。

再 `POST /api/v2/third-party/channels/{channelId}/playback-lease`，请求体例子：`{"protocols":["http-flv","http-fmp4","hls"],"leaseSeconds":120,"absoluteLifetimeSeconds":43200}`。后端只将 `sources[].url` 交给获准用户。到 renewAfter 用同一 Token 续租，播放器无需更换 URL；到绝对期限或收权后重新走业务授权。停止通道与撤销某个播放租约是不同操作。

401 检查 Token/账号/IP/时效；403 不自动扩大权限；404 核对版本、ID 和可见范围；409 先查状态；429 按 Retry-After 退避。批量动作检查 succeeded/failed 每项。非 2xx 不一定同一 JSON 结构，204 不强制解析 JSON。分页、时间单位、枚举大小写、可空字段和默认值均按 OpenAPI 与指南，时间保留 UTC/时区信息。