# 坤典视频监控节点 API 文档版本 `1.2.0` 接口基础地址 `https://kdncjk.yuanjiweilai.com/node/api/v1` 本节点 AppID 通过 X-App-ID 和 Authorization: Bearer <应用密钥> 鉴权,仅操作所属设备与通道。节点管理密钥可用 Authorization: Bearer <节点管理密钥>,按业务可选 X-Client-ID。浏览器控制台使用 HttpOnly 会话。 - 设备和通道路径使用返回对象的内部 id。新增国标设备的 device_id 是 20 位国标编号,保留为字符串。设备级修改与删除要求整台设备归属当前节点。混合绑定设备仅返回本节点视频通道及相关目录。 - 接口从业务服务端通过 HTTPS 调用。不要把长期密钥放进浏览器、URL、日志或 AI 提示词。播放返回的短期地址直接用于媒体连接,不向媒体地址转发 API 鉴权头。 - 实时及历史回放使用返回的 playback_id 控制本应用的会话。每 15 秒 heartbeat,结束发送 stop。轮换或撤销后旧密钥无法续租,原会话按超时清理。 - 错误以 HTTP 状态判断,常见响应包含 msg。400 参数或业务状态异常,401 凭证无效,403 无权访问,404 资源不在本节点,409 配置或操作冲突,429 限流,502/503/504 上游不可用或超时。不得把错误当作空结果。 - 标为“节点管理密钥/后台会话”的接口不适用于节点自签 AppID。中心签发的全平台 AppID 使用独立的中心接入文档。 ## 接入示例 先在节点后台签发 AppID。以下示例从环境变量读取凭证,替换路径中的设备 ID、通道 ID 和时间范围。 ```sh NODE_API='https://kdncjk.yuanjiweilai.com/node/api/v1' ``` ### 获取设备列表 ```sh curl --fail-with-body -X GET "$NODE_API/devices?page=1&size=20" \ -H "X-App-ID: $NODE_APP_ID" \ -H "Authorization: Bearer $NODE_APP_SECRET" ``` 读取 total 和 items[].id。 ### 获取设备通道 ```sh curl --fail-with-body -X GET "$NODE_API/devices/{deviceId}/channels?page=1&size=20" \ -H "X-App-ID: $NODE_APP_ID" \ -H "Authorization: Bearer $NODE_APP_SECRET" ``` 用上一步的设备 id 替换 {deviceId},读取通道 items[].id。 ### 开始实时预览 ```sh curl --fail-with-body -X POST "$NODE_API/channels/{channelId}/live-preview" \ -H "X-App-ID: $NODE_APP_ID" \ -H "Authorization: Bearer $NODE_APP_SECRET" \ -H 'Content-Type: application/json' --data '{ "profile": "main" }' ``` 读取 playback_id、direct、media_node_id、items[].flv 和 items[].webrtc。用同一 AppID 调用会话控制。 ### 查询录像 ```sh curl --fail-with-body -X GET "$NODE_API/channels/{channelId}/device-recordings?start_ms=1764547200000&end_ms=1764550800000" \ -H "X-App-ID: $NODE_APP_ID" \ -H "Authorization: Bearer $NODE_APP_SECRET" ``` 示例时间仅为占位,替换为查询区间的 Unix 毫秒。给录像索引请求预留至少 190 秒。 ### 开始设备回放 ```sh curl --fail-with-body -X POST "$NODE_API/channels/{channelId}/device-playback" \ -H "X-App-ID: $NODE_APP_ID" \ -H "Authorization: Bearer $NODE_APP_SECRET" \ -H 'Content-Type: application/json' --data '{ "start_ms": 1764547200000, "end_ms": 1764550800000 }' ``` 使用完整索引返回的时间范围,每 15 秒续租。结束时发送 stop。 ## 接口参考 ### 读取默认封面 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/app/default-cover` 返回中心配置的 JPEG。 认证方式为节点管理密钥或后台会话。 响应 - `200` 成功 返回 `image/jpeg`。 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 设备默认设置 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/app/device-defaults` 读取中心新增设备的默认设置。 认证方式为节点管理密钥或后台会话。 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 查看节点预览排序 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/app/preview-order` 仅返回当前节点所属设备与通道。 认证方式为节点管理密钥或后台会话。 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 保存节点预览排序 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/app/preview-order` 请求只能包含本节点所属资源。 认证方式为节点管理密钥或后台会话。 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `channel_ranks` | object> | 可选 | 设备内通道排序编号 | | `channels` | object> | 可选 | 按设备 ID 保存通道 ID 数组 | | `device_ranks` | object | 可选 | 设备排序编号 | | `devices` | array | 可选 | 设备 ID 顺序 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 节点抓拍列表 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/captures` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `page` | query | integer | 否 | 页码。默认 `1`。最小 1。最大 1e+06 | | `size` | query | integer | 否 | 每页数量。默认 `24`。最小 1。最大 100 | | `device_id` | query | string | 否 | 设备内部 ID | | `channel_id` | query | string | 否 | 通道内部 ID | | `source` | query | string | 否 | 来源。可选值 `["manual","scheduled","alarm"]` | | `start` | query | string (date-time) | 否 | 起始时间 | | `end` | query | string (date-time) | 否 | 结束时间 | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 抓拍云端同步状态 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/captures/cloud-status` 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 删除抓拍 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/captures/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 抓拍图片 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/captures/{id}/image` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功 返回 `image/jpeg`。 - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 抓拍签名链接 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/captures/{id}/image-link` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 通道列表 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels` 支持 did、key、is_online 和分页。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | | `page` | query | integer | 否 | 页码。默认 `1`。最小 1。最大 100000 | | `size` | query | integer | 否 | 每页条数。默认 `20`。最小 1。最大 500 | | `key` | query | string | 否 | 按名称或国标编号搜索。最多 256 字符 | | `is_online` | query | string | 否 | 在线状态。可选值 `["true","false"]` | | `did` | query | string | 否 | 设备内部 ID | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · items[].id` | string | — | 该设备或通道的内部 ID | | `响应 · items[].is_online` | boolean | — | 在线状态 | | `响应 · items[].name` | string | — | 名称 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 删除通道 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}` | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 修改通道名称 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}` 保留原通道及设备身份。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `device_id` | string | 可选 | 如传入,必须与原设备编号一致 | | `name` | string | 必填 | 通道名称 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 关闭AI `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/ai/disable` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 开启AI `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/ai/enable` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 报警目标标注 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/alarm-target-settings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 报警目标标注 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/alarm-target-settings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `confirmed_human_only` | boolean | 必填 | 是否确认设备仅推送人形告警 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 创建抓拍 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/captures` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 提取设备录像 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-downloads` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `end_ms` | integer | 必填 | 结束 Unix 毫秒,必须晚于起点,区间最长 24 小时 | | `start_ms` | integer | 必填 | 起始 Unix 毫秒 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 提取状态 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-downloads/{job}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `job` | path | string | 是 | 录像提取任务 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 提取文件 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-downloads/{job}/file` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `job` | path | string | 是 | 录像提取任务 ID | 响应 - `200` 成功 返回 `video/mp4`。 - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 开始设备回放 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-playback` start_ms/end_ms Unix毫秒,独立 playback_id 和直接播放地址,最长24小时。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `end_ms` | integer | 必填 | 结束 Unix 毫秒,必须晚于起点,区间最长 24 小时 | | `start_ms` | integer | 必填 | 起始 Unix 毫秒 | 响应 - `200` 播放会话及地址 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · direct` | boolean | — | 是否返回直连地址 | | `响应 · items` | array | — | | | `响应 · items[].flv` | string | — | FLV 地址 | | `响应 · items[].webrtc` | string | — | WebRTC 播放地址 | | `响应 · media_node_id` | string | — | 媒体节点 ID | | `响应 · playback_id` | string | — | 用于控制当前会话 | - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 回放控制 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-playback/{playback}` action heartbeat/stop/pause/resume/speed;speed传 scale。每15秒续租,长暂停30秒后从暂停位置重建自己的会话并恢复倍速。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `playback` | path | string | 是 | 此次预览或回放返回的 playback_id | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `action` | string | 必填 | 回放控制。可选值 `["heartbeat","stop","pause","resume","speed"]` | | `scale` | number | 可选 | 仅切换倍速时传 | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 查询设备录像 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-recordings` start_ms/end_ms Unix毫秒,最长24小时。最多等待190秒,完整成功才返回 items,失败不得当作空列表。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | | `start_ms` | query | integer | 是 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 是 | 结束 Unix 毫秒,必须晚于起点,区间最长 24 小时 | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 渐进录像索引 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/device-recordings/progress` NDJSON,items/total/received/complete/error。只有 complete=true 才表示收齐;中断、error、缺少 complete 都是失败。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | | `start_ms` | query | integer | 是 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 是 | 结束 Unix 毫秒,必须晚于起点,区间最长 24 小时 | 响应 - `200` 逐行 JSON。只有 complete=true 表示完整成功。 返回 `application/x-ndjson`。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 实时预览 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/live-preview` profile main/sub;返回 direct、media_node_id、playback_id 与带短期凭证的直接播放地址 items[].webrtc/flv。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `profile` | string | 可选 | 码流。可选值 `["main","sub"]`。默认 `"main"` | ```json { "profile": "main" } ``` 响应 - `200` 播放会话及地址 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · direct` | boolean | — | 是否返回直连地址 | | `响应 · items` | array | — | | | `响应 · items[].flv` | string | — | FLV 地址 | | `响应 · items[].webrtc` | string | — | WebRTC 播放地址 | | `响应 · media_node_id` | string | — | 媒体节点 ID | | `响应 · playback_id` | string | — | 用于控制当前会话 | - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 实时会话控制 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/live-preview/{playback}` action heartbeat/stop/keyframe。每15秒续租,仅控制同 X-Client-ID 的独立会话。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `playback` | path | string | 是 | 此次预览或回放返回的 playback_id | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `action` | string | 必填 | 会话动作。可选值 `["heartbeat","stop","keyframe"]` | ```json { "action": "heartbeat" } ``` 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 更新实时预览封面 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/live-preview/{playback}/cover` 上传当前会话的有效 JPEG,大小不超过 160 KiB。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `playback` | path | string | 是 | 此次预览或回放返回的 playback_id | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `image/jpeg`,必填。 有效 JPEG,最大 160 KiB 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 读取通道媒体信息 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/media_info` | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `playback_id` | query | string | 否 | 指定实时或回放会话,省略读取当前通道默认流 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 主码流预览 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/play` 与 live-preview 主码流相同。使用 live-preview/{playback} 管理会话。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 播放会话及地址 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · direct` | boolean | — | 是否返回直连地址 | | `响应 · items` | array | — | | | `响应 · items[].flv` | string | — | FLV 地址 | | `响应 · items[].webrtc` | string | — | WebRTC 播放地址 | | `响应 · media_node_id` | string | — | 媒体节点 ID | | `响应 · playback_id` | string | — | 用于控制当前会话 | - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 云台控制 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/ptz/control` 真实移动镜头。hold_id 每次按住唯一,action continuous/stop/preset;direction、speed(0..1)、preset_id、preset_op。连续按住每300ms发送,松开立即stop;1.5秒无续按自动停止。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `action` | string | 必填 | 云台动作。可选值 `["continuous","stop","preset"]` | | `direction` | string | 可选 | 连续移动时填写,如 left 或 right。可选值 `["up","down","left","right","upleft","upright","downleft","downright","zoomin","zoomout"]` | | `hold_id` | string | 必填 | 本次按住或预置位操作的唯一编号,停止沿用同一编号。最多 80 字符。格式 `^[a-zA-Z0-9_-]{1,80}$` | | `preset_id` | string | 可选 | preset 时填写,字符串编号 | | `preset_op` | string | 可选 | preset 时填写。可选值 `["goto","set","remove"]` | | `speed` | number | 可选 | 连续移动时必填,大于 0 且不超过 1。大于 0。最大 1 | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 预置位列表 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/ptz/presets` 返回设备真实名称与平台补充名称来源。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 设置平台预置位名称 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/ptz/presets/{preset}/name` 空名称清除平台补充名称,设备上的预置位不受影响。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `preset` | path | string | 是 | 预置位编号 | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `name` | string | 必填 | 补充名称 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 显式选择七牛实时或回放 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/qiniu/play` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `end_ms` | integer | 可选 | 结束 Unix 毫秒 | | `protocol` | string | 可选 | 实时可选协议;历史固定 FLV。可选值 `["webrtc","flv"]` | | `start_ms` | integer | 可选 | 起始 Unix 毫秒 | ```json { "protocol": "flv" } ``` 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 控制自己的七牛回放 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/qiniu/sessions/{session}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `session` | path | string | 是 | 七牛回放返回的会话 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `action` | string | 必填 | 七牛回放动作。可选值 `["heartbeat","stop","pause","resume","speed"]` | | `scale` | number | 可选 | 倍速 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 设置录像策略 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/record_mode` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `mode` | string | 可选 | 录像模式。可选值 `["always","ai","none"]` | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 录像状态/控制 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/recording` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 录像状态/控制 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/recording` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `action` | string | 必填 | 录像动作。可选值 `["start","stop"]` | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 节点绑定分享 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/shares` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 节点绑定分享 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/shares` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `expires_at` | integer | 必填 | Unix 秒,未来一年内 | | `playback` | boolean | 可选 | 允许回放 | | `presets` | boolean | 可选 | 允许预置位 | | `ptz` | boolean | 可选 | 允许云台 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 分享访问记录 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/shares/{share}/visits` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `share` | path | string | 是 | 分享 ID | | `page` | query | integer | 否 | 页码。默认 `1`。最小 1 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 读取通道封面 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/snapshot` 有封面时返回 JPEG。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功 返回 `image/jpeg`。 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 获取当前节点封面地址 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/snapshot` 返回 link,空字符串表示还没有封面。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### AI区域 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/zones` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### AI区域 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/zones` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `color` | string | 可选 | 十六进制颜色 | | `coordinates` | array | 可选 | 区域坐标 | | `labels` | array | 可选 | 检测标签 | | `name` | string | 可选 | 区域名称 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 删除AI区域 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/channels/{id}/zones/{name}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `name` | path | string | 是 | 区域名称 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 设备列表 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices` 分页、搜索与在线状态筛选,包含离线和未播放设备。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | | `page` | query | integer | 否 | 页码。默认 `1`。最小 1。最大 100000 | | `size` | query | integer | 否 | 每页条数。默认 `20`。最小 1。最大 500 | | `key` | query | string | 否 | 按名称或国标编号搜索。最多 256 字符 | | `is_online` | query | string | 否 | 在线状态。可选值 `["true","false"]` | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · items[].id` | string | — | 该设备或通道的内部 ID | | `响应 · items[].is_online` | boolean | — | 在线状态 | | `响应 · items[].name` | string | — | 名称 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 新增设备 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/devices` 新增国标设备并绑定当前节点。省略 device_id,由管理中心生成 20 位编号,并仅在本次成功响应返回 sip_access。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `device_id` | string | 可选 | 可选。省略或传空字符串时生成 20 位国标编号。显式指定编号时保留原行为,不返回接入密码。。格式 `^([0-9]{20})?$` | | `name` | string | 可选 | 设备名称 | | `password` | string | 可选 | 注册密码。自动编号时留空将生成设备专用密码。 | 响应 - `200` 设备及自动编号模式的一次性 SIP 接入参数。不要将注册密码写入日志。 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · device_id` | string | — | 20 位设备国标编号,也是设备注册用户名 | | `响应 · id` | string | — | 设备内部 ID | | `响应 · sip_access` | object | — | 仅自动编号模式新建成功时返回 | | `响应 · sip_access.domain` | string | — | SIP 域 | | `响应 · sip_access.host` | string | — | 中心 SIP 服务 IP 或域名 | | `响应 · sip_access.password` | string | — | 设备专用注册密码 | | `响应 · sip_access.port` | integer | — | 中心 SIP 服务端口 | | `响应 · sip_access.server_id` | string | — | 中心 SIP 服务 ID | - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 - `503` 中心 SIP 配置不完整,或暂时无法生成编号 ### 设备及通道摘要 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices/channels` 用于列表预览。每台设备 children 最多 5 路,完整列表请调用设备通道接口。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `page` | query | integer | 否 | 页码。默认 `1`。最小 1。最大 100000 | | `size` | query | integer | 否 | 每页条数。默认 `20`。最小 1。最大 500 | | `key` | query | string | 否 | 按名称或国标编号搜索。最多 256 字符 | | `is_online` | query | string | 否 | 在线状态。可选值 `["true","false"]` | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · items[].id` | string | — | 该设备或通道的内部 ID | | `响应 · items[].is_online` | boolean | — | 在线状态 | | `响应 · items[].name` | string | — | 名称 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 删除设备 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}` 仅整台独占设备,删除同时作用于中心及其全部通道,不影响其他节点。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 设备详情 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}` 不返回注册密码等敏感字段。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 修改设备 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}` 仅整台独占设备,支持 name、password(留空保留)、stream_mode(0/1),不更改国标身份。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `name` | string | 可选 | 设备名称 | | `password` | string | 可选 | 注册密码,留空保留 | | `stream_mode` | integer | 可选 | 媒体传输配置。可选值 `[0,1]` | 响应 - `200` 成功;敏感播放URL仅供当前观看者,不得记入日志。 - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 设备国标报警接收 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/alarm-settings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 设备国标报警接收 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/alarm-settings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `all_types` | boolean | 可选 | 是否接收全部类型 | | `enabled` | boolean | 可选 | 是否接收 | | `types` | array | 可选 | 报警方式及子类型联合键,从 GET 返回的 options 取值 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 设备抓拍策略 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/capture-settings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 设备抓拍策略 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/capture-settings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `alarm_enabled` | boolean | 可选 | 报警抓拍 | | `daily_times` | array | 可选 | 本地每日时间 HH:mm | | `interval_seconds` | integer | 可选 | 周期秒数 | | `preset_delay_seconds` | integer | 可选 | 到达预置位后等待秒数。可选值 `[10]` | | `preset_enabled` | boolean | 可选 | 定时抓拍时启用预置位 | | `preset_targets` | array | 可选 | 预置位目标 | | `preset_targets[].channel_id` | string | 可选 | 通道内部 ID | | `preset_targets[].preset_id` | string | 可选 | | | `schedule_mode` | string | 可选 | 调度方式。可选值 `["interval","daily"]` | | `scheduled_enabled` | boolean | 可选 | 定时抓拍 | | `timezone` | string | 可选 | IANA 时区名称 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 更新设备目录 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/catalog` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 设备通道 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/channels` 仅返回当前节点所属视频通道。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `X-Client-ID` | header | string | 否 | 仅旧版节点管理密钥集成可选。保持稳定,1–64 位字母数字下划线或横线,默认 default。AppID 会话按应用归属。。默认 `"default"` | | `page` | query | integer | 否 | 页码。默认 `1`。最小 1。最大 100000 | | `size` | query | integer | 否 | 每页条数。默认 `20`。最小 1。最大 500 | | `key` | query | string | 否 | 按名称或国标编号搜索。最多 256 字符 | | `is_online` | query | string | 否 | 在线状态。可选值 `["true","false"]` | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · items[].id` | string | — | 该设备或通道的内部 ID | | `响应 · items[].is_online` | boolean | — | 在线状态 | | `响应 · items[].name` | string | — | 名称 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `400` 参数无效或设备非独占 - `401` 密钥无效 - `403` 会话归属不匹配 - `404` 资源不属于此节点 - `409` 节点未配置或冲突 - `429` 并发过多 - `502` 中心不可达或响应异常 ### 修改设备名称 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/name` 整台设备必须归属本节点。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `name` | string | 必填 | 设备名称。最多 128 字符 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 设备重启 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/reboot` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 流量卡绑定 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/sim-card` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 流量卡绑定 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/sim-card` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `kind` | string | 可选 | 号码类型 | | `number` | string | 必填 | 卡号;空字符串解除绑定 | | `reference_number` | string | 可选 | 独立保存的我方号码 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 查询已保存流量卡 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/devices/{id}/sim-card/query` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 节点告警列表/删除 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/events` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `max_id` | query | integer | 是 | 查询列表返回的最大编号,限定批量清理范围 | | `start_ms` | query | integer | 否 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 否 | 结束 Unix 毫秒 | | `did` | query | string | 否 | 设备内部 ID | | `cid` | query | string | 否 | 通道内部 ID | | `label` | query | string | 否 | 检测标签 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 节点告警列表/删除 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/events` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `page` | query | integer | 否 | 页码。默认 `1` | | `size` | query | integer | 否 | 每页条数 | | `max_id` | query | integer | 否 | 可见事件编号上限 | | `start_ms` | query | integer | 否 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 否 | 结束 Unix 毫秒 | | `did` | query | string | 否 | 设备内部 ID | | `cid` | query | string | 否 | 通道内部 ID | | `label` | query | string | 否 | 检测标签 | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · max_id` | integer | — | 本节点告警最大编号 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 读取告警原图 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/events/image/{path}` 使用告警响应中已有的相对图片路径。中间目录以斜杠连接。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `path` | path | string | 是 | 库存记录的相对资源路径 | 响应 - `200` 成功 返回 `image/jpeg`。 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 告警详情/更新/删除 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 告警详情/更新/删除 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 告警详情/更新/删除 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `ended_at` | integer | 可选 | 事件结束 Unix 毫秒 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 独立告警回放 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}/device-playback` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `end_ms` | integer | 必填 | 结束 Unix 毫秒,必须晚于起点,区间最长 24 小时 | | `start_ms` | integer | 必填 | 起始 Unix 毫秒 | 响应 - `200` 播放会话及地址 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · direct` | boolean | — | 是否返回直连地址 | | `响应 · items` | array | — | | | `响应 · items[].flv` | string | — | FLV 地址 | | `响应 · items[].webrtc` | string | — | WebRTC 播放地址 | | `响应 · media_node_id` | string | — | 媒体节点 ID | | `响应 · playback_id` | string | — | 用于控制当前会话 | - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 告警定位设备录像 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}/device-recordings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `before_seconds` | query | integer | 否 | 告警前定位秒数 | | `after_seconds` | query | integer | 否 | 告警后定位秒数 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 报警小图状态 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}/thumbnail` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 读取报警小图 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/events/{id}/thumbnail/image` | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功 返回 `image/jpeg`。 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 节点接入信息 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/integration-info` 返回已配置的 SIP 接入地址及节点媒体目标。 认证方式为节点管理密钥或后台会话。 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### OpenAPI 接口定义 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/openapi.json` 返回当前节点的结构化 OpenAPI 文档。 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 保存节点绑定 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/playback-node-bindings` 节点仅可执行中心允许的归属内操作。 认证方式为节点管理密钥或后台会话。 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `kind` | string | 必填 | 绑定类别。可选值 `["device","channel"]` | | `node_id` | string | 可选 | 节点 ID | | `target_id` | string | 必填 | 内部设备或通道 ID | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 节点和绑定摘要 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/playback-nodes` 返回本节点及所属绑定。 认证方式为节点管理密钥或后台会话。 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 按库存路径读取本节点录像 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recording-files` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `path` | query | string | 是 | 录像记录的相对文件路径 | | `Range` | header | string | 否 | 可选的字节范围 | 响应 - `200` 录像文件,可使用 Range 获取部分内容 返回 `video/mp4`。 - `206` 使用 Range 时返回文件的部分字节 - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 本地录像列表 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `page` | query | integer | 否 | 页码。默认 `1` | | `size` | query | integer | 否 | 每页条数 | | `start_ms` | query | integer | 否 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 否 | 结束 Unix 毫秒 | | `cid` | query | string | 否 | 通道内部 ID | | `app` | query | string | 否 | 媒体应用名 | | `stream` | query | string | 否 | 媒体流 ID | 响应 - `200` 分页列表 返回 `application/json`。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `响应 · items` | array | — | 本页记录 | | `响应 · total` | integer | — | 符合范围和筛选条件的总量 | - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 生成通道 HLS 清单 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/channels/{cid}/index.m3u8` 请求返回的录像片段时也需携带鉴权请求头。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `cid` | path | string | 是 | 通道内部 ID | | `start_ms` | query | integer | 是 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 是 | 结束 Unix 毫秒,必须晚于起点 | 响应 - `200` 成功 返回 `application/vnd.apple.mpegurl`。 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 月度有录像日期 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/monthly` | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `cid` | query | string | 否 | 通道内部 ID | | `year` | query | integer | 否 | 公历年份 | | `month` | query | integer | 否 | 月份。最小 1。最大 12 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 录像时间轴 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/timeline` | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `cid` | query | string | 是 | 通道内部 ID | | `start_ms` | query | integer | 否 | 起始 Unix 毫秒 | | `end_ms` | query | integer | 否 | 结束 Unix 毫秒 | 响应 - `200` 请求成功 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问 ### 本地录像详情/更新/删除 `DELETE https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 本地录像详情/更新/删除 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 本地录像详情/更新/删除 `PUT https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/{id}` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 请求体 `application/json`,必填。 | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `object_count` | integer | 可选 | 检测对象数量 | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 本地录像文件 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/{id}/download` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | | `Range` | header | string | 否 | 可选的字节范围 | 响应 - `200` 录像文件,可使用 Range 获取部分内容 返回 `video/mp4`。 - `206` 使用 Range 时返回文件的部分字节 - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 查询或主动上传已完成本地录像 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/{id}/qiniu` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 查询或主动上传已完成本地录像 `POST https://kdncjk.yuanjiweilai.com/node/api/v1/recordings/{id}/qiniu` 仅限本节点所属设备或通道;混合绑定设备不允许设备级修改。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `id` | path | string | 是 | 通过列表获得的内部资源 ID | 响应 - `200` 成功;返回资源对象或分页items/total - `401` 节点鉴权失败 - `403` 超出节点范围 - `404` 资源不存在或不属于节点 ### 读取节点录像文件 `GET https://kdncjk.yuanjiweilai.com/node/api/v1/static/recordings/{path}` 使用录像记录中保存的相对路径,中间目录以斜杠连接。 | 参数 | 位置 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `path` | path | string | 是 | 库存记录的相对资源路径 | | `Range` | header | string | 否 | 可选的字节范围 | 响应 - `200` 录像文件,可使用 Range 获取部分内容 返回 `video/mp4`。 - `206` 使用 Range 时返回文件的部分字节 - `401` 鉴权失败 - `403` 操作不在当前权限范围 - `404` 资源不可访问