API 对接：先完成一个真实用例
这组文档写给程序员。把权限受限的 API Token 保存在自己的业务后端，先完成“查询资源 → 提交动作 → 确认用户结果”的一个小闭环，再查具体模块接口。客户端只接收获准资源的短时地址或一次性票据。
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 Token 完成直播、录像、删除和 RTC | 5 分钟跑通、27 个接口参考 |
| 系统与运维 | 查健康、版本、节点、配置、日志、后台任务 | 系统、运维与节点接口 |
| 账号与授权 | 管用户、角色、令牌、审计和授权额度 | 登录、账号、安全与授权接口 |
| 统一资源 | 查设备、通道、流、状态和统一控制入口 | 设备、通道、流与统一资源接口 |
| 录像生产 | 配计划、检索文件、播放下载、裁剪合并 | 录像、文件、裁剪与磁盘接口 |
| 国标设备 | 做 GB28181 注册、目录、点播、回放和控制 | GB28181 接口 |
| ONVIF 设备 | 做发现、Profile、PTZ、图像参数和事件 | ONVIF 接口 |
| 实时协作 | 做 RTC/SFU 会议、成员、白板、投屏和录制 | RTC 入会/媒体/主持 API、录制档案 API |
| 通道最近画面 | 查询截图参数并安全交付图片 | 周期截图 API |
当前随版第三方 Skill 提供 1.0.0.169 的公开契约，共 626 个公开操作，覆盖完整业务及管理 API；精确字段和权限请读取同版资产并核对部署版本。RTC SDK 函数以同批交付类型和源码为准。
推荐的集成顺序
- 用
/health确认网络和进程可达。 - 用管理员账号创建一枚独立 API Token，不要让程序长期保存人的密码。
- 调
/api/v2/auth/me或一个只读业务接口验证身份与权限。 - 先完成一个最小闭环，例如“查通道 → 启动预览 → 查询流状态 → 停止预览”。
- 把写操作改成“提交动作 → 保存返回 ID → 查询终态或订阅事件”。
- 最后才增加批量调用、自动重试和并发控制。
三条边界必须记住
- HTTP
200或202常常只代表平台接受了请求，不代表摄像机、媒体节点或录像任务已经完成。 - 标成“内部接口、内部回调、节点本机接口”的路由不是第三方扩展点，业务系统不要模拟这些身份。
- 浏览器只拿短时会话或一次性票据；长期 API Token 放在你自己的服务端，不放进网页、App 安装包或公开仓库。
精确字段从哪里查
讲人话的接口页负责帮你选对接口；与部署版本一起提供的 OpenAPI 负责精确字段、枚举、请求体和响应体。Postman 集合适合联调，生成 SDK 后仍要自己处理异步终态、文件、WebSocket、SDP、超时和重试。
下一步先看调用前准备和五分钟跑通，再按业务任务进入对应接口专页。Web/H5、原生移动端或 UniApp 会议应用另从 RTC SDK 接入开始。