API 与请求响应模型索引

AKStream.Next v2 业务 API 位于 /api/v2。完整契约随产品版本交付，不应使用“当前网站最新接口”调用旧部署。

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

flowchart LR
    A[部署版本] --> B[同版本 openapi-v2.json]
    B --> C[接口路径与权限]
    B --> D[请求响应 Schema]
    C --> E[客户端与契约测试]
    D --> E

契约资产

• Documentation/SKILL/akstream-next-integration/references/openapi.json：机器可读 OpenAPI。
• Documentation/SKILL/akstream-next-integration/references/postman-collection.json：按领域分组的请求集合。
• Documentation/SKILL/akstream-next-integration/references/postman-environment.json：不含真实 Token 的环境模板。
• 《API 完整接口索引》：操作、权限与摘要。
• 《API 请求响应模型字段索引》：Schema 字段参考。

这些资产由同一 OpenAPI 事实源生成，发布门禁会核对操作与模型数量。

在线 Swagger

Swagger/Knife4j 页面、静态资源和 OpenAPI JSON 只允许已登录 WebUI 的交互式后台会话读取。普通 API Token 不能枚举接口目录。无人值守构建和 SDK 生成使用包内资产。

请求约定

• JSON 使用 UTF-8，时间使用 ISO 8601 并保留时区语义。
• 分页通常从 page=1 开始，pageSize 有服务端上限。
• 可空字段与空字符串语义不同。
• 客户端忽略未知响应字段并容忍新状态值。
• 非 2xx 保留 HTTP 状态、Content-Type、原始响应与 TraceId。
• 文件、Range、SDP 和 WebSocket 使用各自协议处理。

权限

使用 Bearer API Token 时按领域申请最小权限。内部节点、Agent、媒体服务 WebHook 与安装向导接口不是普通第三方 API。系统文件树、秘密与高风险生命周期操作还要求交互式会话。

查找接口

先从任务选择领域：

• 设备与通道：devices、channels、GB28181、ONVIF。
• 实时流与播放：streams、media servers、tickets。
• 录像：recording、files、record plans、cut/merge。
• 录像画面内容检索：录像智能检索 API。
• RTC：rooms、participants、media sessions、events。
• 运维：system、nodes、configuration、tasks、logs。
• 安全：users、roles、API tokens、audit。

找到操作后，再查对应请求/响应 Schema 和权限。需要代码示例时转到 OpenAPI、Postman 与客户端资产。