# API 对接：先完成一个真实用例

这组文档写给程序员。把权限受限的 API Token 保存在自己的业务后端，先完成“查询资源 → 提交动作 → 确认用户结果”的一个小闭环，再查具体模块接口。客户端只接收获准资源的短时地址或一次性票据。

```mermaid
flowchart LR
    A[你的服务端] -->|API Token + HTTPS| B[AKStream.Next API]
    B --> C[设备 / 通道 / 录像 / RTC]
    B -->|短时播放或入会票据| D[你的浏览器或 App]
    D --> E[MediaServer]
```

## 先按业务层找接口

| 层次 | 你想完成的事 | 先看哪一页 |
|---|---|---|
| 本次更新 | 核对已安装版本与该版本真正提供的接口 | 版本更新说明、能力边界 |
| AI 辅助开发 | 让 AI 使用公开接口、RTC SDK 和全部公开文档完成任务 | AI 辅助对接与二次开发 |
| 连接与身份 | 确认服务地址、登录、创建 API Token、处理权限 | 调用前准备、[认证与错误](api-security.md) |
| 第三方业务后端 | 不登录页面，用 API Token 完成直播、录像、删除和 RTC | [5 分钟跑通](third-party-start.md)、[27 个接口参考](api-third-party-contract.md) |
| 系统与运维 | 查健康、版本、节点、配置、日志、后台任务 | [系统、运维与节点接口](local-run.md) |
| 账号与授权 | 管用户、角色、令牌、审计和授权额度 | [登录、账号、安全与授权接口](repository.md) |
| 统一资源 | 查设备、通道、流、状态和统一控制入口 | [设备、通道、流与统一资源接口](webui.md) |
| 录像生产 | 配计划、检索文件、播放下载、裁剪合并 | [录像、文件、裁剪与磁盘接口](database.md) |
| 国标设备 | 做 GB28181 注册、目录、点播、回放和控制 | [GB28181 接口](add-module.md) |
| ONVIF 设备 | 做发现、Profile、PTZ、图像参数和事件 | [ONVIF 接口](testing-release.md) |
| 实时协作 | 做 RTC/SFU 会议、成员、白板、投屏和录制 | [RTC 入会/媒体/主持 API](api-rtc.md)、[录制档案 API](api-rtc-archive.md) |
| 通道最近画面 | 查询截图参数并安全交付图片 | 周期截图 API |

当前随版第三方 Skill 提供 1.0.0.169 的公开契约，共 626 个公开操作，覆盖完整业务及管理 API；精确字段和权限请读取同版资产并核对部署版本。RTC SDK 函数以同批交付类型和源码为准。

## 推荐的集成顺序

1. 用 `/health` 确认网络和进程可达。
2. 用管理员账号创建一枚独立 API Token，不要让程序长期保存人的密码。
3. 调 `/api/v2/auth/me` 或一个只读业务接口验证身份与权限。
4. 先完成一个最小闭环，例如“查通道 → 启动预览 → 查询流状态 → 停止预览”。
5. 把写操作改成“提交动作 → 保存返回 ID → 查询终态或订阅事件”。
6. 最后才增加批量调用、自动重试和并发控制。

## 三条边界必须记住

- HTTP `200` 或 `202` 常常只代表平台接受了请求，不代表摄像机、媒体节点或录像任务已经完成。
- 标成“内部接口、内部回调、节点本机接口”的路由不是第三方扩展点，业务系统不要模拟这些身份。
- 浏览器只拿短时会话或一次性票据；长期 API Token 放在你自己的服务端，不放进网页、App 安装包或公开仓库。

## 精确字段从哪里查

讲人话的接口页负责帮你选对接口；与部署版本一起提供的 OpenAPI 负责精确字段、枚举、请求体和响应体。Postman 集合适合联调，生成 SDK 后仍要自己处理异步终态、文件、WebSocket、SDP、超时和重试。

下一步先看调用前准备和[五分钟跑通](third-party-start.md)，再按业务任务进入对应接口专页。Web/H5、原生移动端或 UniApp 会议应用另从 [RTC SDK 接入](../sdk/home.md)开始。