设备、通道、流与统一资源接口
这一层把不同接入方式归一为设备、通道和流。做业务集成时优先调用统一通道与协议视图；只有协议特有能力才进入 GB28181 或 ONVIF 专页。
本页覆盖 69 个接口。每一行都回答五件事：接口地址、它做什么、何时调用、如何确认完成、谁可以调用。参数字段的精确定义以同版本 OpenAPI 为准。
“业务接口”可以由 WebUI 或第三方系统按权限调用；“管理员接口”需要后台管理员；“内部接口/内部回调”只允许产品组件之间使用。
视频通道与流
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/channels |
查询视频通道列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
page、pageSize、mediaServerId、nodeId、protocol、vhost、app、stream、streamId、deviceId、deviceChannelId、enabled、autoVideo、autoRecord、noPlayerBreak、hasAudio、hasPtz、isShareChannel、desiredState、actualState、sourceUrl、keyword |
POST /api/v2/channels |
创建视频通道。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
SaveVideoChannelRequest |
DELETE /api/v2/channels/{channelId} |
删除视频通道。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
channelId（必填） |
GET /api/v2/channels/{channelId} |
查看视频通道。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
channelId（必填） |
PUT /api/v2/channels/{channelId} |
更新视频通道。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
channelId（必填）、SaveVideoChannelRequest |
POST /api/v2/channels/{channelId}/activate |
激活待接入视频通道。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>channels.manage |
channelId（必填）、ActivateVideoChannelRequest |
POST /api/v2/channels/{channelId}/pause |
人工暂停视频通道自动恢复。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
channelId（必填） |
POST /api/v2/channels/{channelId}/ptz |
控制视频通道 云台动作。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>devices.control |
channelId（必填）、VideoChannelPtzRequest |
GET /api/v2/channels/{channelId}/ptz/capabilities |
查看视频通道 云台动作 能力。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
channelId（必填） |
POST /api/v2/channels/{channelId}/ptz/capabilities/refresh |
刷新视频通道 云台动作 能力。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>devices.control |
channelId（必填） |
GET /api/v2/channels/{channelId}/ptz/settings |
查看设备 云台动作 能力与人工开关。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
channelId（必填） |
PUT /api/v2/channels/{channelId}/ptz/settings |
保存 云台动作 使用开关和 GB28181 未上报能力的管理员确认，不修改设备报告字段。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>channels.manage |
channelId（必填）、SaveChannelPtzSettingsRequest |
POST /api/v2/channels/{channelId}/retry |
清理自动拉流退避状态并立即重试。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>channels.manage |
channelId（必填） |
POST /api/v2/channels/{channelId}/return-to-pending |
将视频通道退回待激活资产池。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
channelId（必填） |
GET /api/v2/channels/{channelId}/runtime-logs |
查询通道运行审计时间线。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
channelId（必填）、Page（必填）、PageSize（必填）、SinceHours（必填）、Level、Category |
GET /api/v2/channels/{channelId}/snapshots |
查询通道周期截图设置、在线状态及带鉴权的图片预览和下载地址。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>streams.play |
channelId（必填） |
GET /api/v2/channels/{channelId}/snapshots/{slot} |
预览或下载指定周期截图JPEG。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>streams.play |
channelId（必填）、slot（必填）、v、download |
POST /api/v2/channels/{channelId}/snapshots/access |
签发绑定当前通道和view/download动作的短时截图票据。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>streams.play |
channelId（必填）、ChannelSnapshotAccessRequest |
PUT /api/v2/channels/{channelId}/snapshots/settings |
05 视频通道与流：PUT /api/v2/channels/{channelId}/snapshots/settings。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
channelId（必填）、ChannelSnapshotSettings |
POST /api/v2/channels/{channelId}/start |
启动视频通道拉流。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>channels.manage |
channelId（必填） |
POST /api/v2/channels/{channelId}/stop |
停流并人工暂停视频通道。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>channels.manage |
channelId（必填） |
GET /api/v2/channels/asset-transfer/export |
导出设备、协议通道、统一通道和分组。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
无业务参数 |
POST /api/v2/channels/asset-transfer/import |
预览或确认导入接入资产。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
AssetTransferImportRequest |
GET /api/v2/channels/groups |
查询视频设备分组。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
无业务参数 |
POST /api/v2/channels/groups |
创建视频设备分组。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
SaveChannelGroupRequest |
DELETE /api/v2/channels/groups/{groupKey} |
删除空视频设备分组。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
groupKey（必填） |
PUT /api/v2/channels/groups/{groupKey} |
更新视频设备分组。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>channels.manage |
groupKey（必填）、SaveChannelGroupRequest |
GET /api/v2/channels/pending-activation |
查询待激活视频通道列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
page、pageSize、protocol、deviceId、keyword |
GET /api/v2/channels/recording-search/capability |
查询通道图文检索选项是否可编辑。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>channels.view |
无业务参数 |
GET /api/v2/streams/commands |
查询流生命周期命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>streams.view |
mediaServerId、streamId、state、page、pageSize |
GET /api/v2/streams/players |
查询流媒体服务播放者会话。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>streams.view |
mediaServerId、app、streamId、schema、state、active、page（必填）、pageSize（必填） |
GET /api/v2/streams/sessions |
查询流会话状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>streams.view |
mediaServerId、streamId、state |
POST /api/v2/streams/smoke-tests/rtsp |
执行 RTSP 拉流烟测。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>streams.manage |
RtspSmokeTestRequest |
POST /api/v2/streams/smoke-tests/rtsp/batch |
批量执行 RTSP 拉流烟测。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>streams.manage |
RtspSmokeBatchTestRequest |
POST /api/v2/streams/start-proxy |
创建拉流启动命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>streams.manage |
StartStreamCommandRequest |
POST /api/v2/streams/stop-proxy |
创建拉流停止命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>streams.manage |
StopStreamCommandRequest |
协议统一视图
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/protocols/{protocol}/devices/{deviceId} |
查看协议设备。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
protocol（必填）、deviceId（必填） |
GET /api/v2/protocols/{protocol}/devices/{deviceId}/channels |
查询协议设备通道。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
protocol（必填）、deviceId（必填）、page、pageSize、status、channelType、hasAudio、hasPtz、videoChannelId、keyword |
POST /api/v2/protocols/{protocol}/devices/{deviceId}/channels |
保存协议设备通道。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
protocol（必填）、deviceId（必填）、SaveProtocolChannelRequest |
POST /api/v2/protocols/{protocol}/devices/{deviceId}/offline |
标记协议设备离线。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
protocol（必填）、deviceId（必填） |
POST /api/v2/protocols/{protocol}/devices/{deviceId}/online |
标记协议设备在线。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
protocol（必填）、deviceId（必填） |
GET /api/v2/protocols/acceptance |
查看协议验收总览。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
checkDatabase、checkZlm、includeSystemReadiness |
GET /api/v2/protocols/alarms/events |
统一查询 GB28181、ONVIF 等协议告警事件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
page、pageSize、protocol、deviceId、channelId、alarmPriority、alarmMethod、alarmType、ackStatus、begin、end、from、to、sinceHours、keyword |
POST /api/v2/protocols/alarms/events/{alarmEventId}/acknowledge |
确认协议告警事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.control |
alarmEventId（必填）、ProtocolAlarmDispositionRequest |
POST /api/v2/protocols/alarms/events/{alarmEventId}/clear |
清除协议告警事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.control |
alarmEventId（必填）、ProtocolAlarmDispositionRequest |
POST /api/v2/protocols/alarms/events/{alarmEventId}/ignore |
忽略协议告警事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.control |
alarmEventId（必填）、ProtocolAlarmDispositionRequest |
POST /api/v2/protocols/alarms/events/{alarmEventId}/status |
按指定状态更新协议告警事件。 | 做页面概览、运行监控或排障时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.control |
alarmEventId（必填）、ProtocolAlarmStatusUpdateRequest |
POST /api/v2/protocols/alarms/events/batch/{action} |
批量确认、本地清除或忽略协议告警。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.control |
action（必填）、ProtocolAlarmBatchDispositionRequest |
GET /api/v2/protocols/alarms/events/stats |
统计协议告警事件处置状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
protocol、deviceId、channelId、alarmPriority、alarmMethod、alarmType、ackStatus、begin、end、from、to、sinceHours、keyword |
GET /api/v2/protocols/channels/orphan-video-bindings |
查询协议通道孤儿视频绑定。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
page、pageSize、protocol、deviceId、channelId、keyword |
POST /api/v2/protocols/channels/orphan-video-bindings/clear |
清空协议通道孤儿视频绑定。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.control |
ClearProtocolOrphanVideoBindingRequest |
GET /api/v2/protocols/commands |
统一查询 GB28181、ONVIF 等协议命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
statusMode、page、pageSize、protocol、status、commandType、deviceId、channelId、nodeId、correlationId、requestedBy、from、to、sinceHours、keyword |
GET /api/v2/protocols/commands/{commandId} |
查看协议命令详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
commandId（必填） |
GET /api/v2/protocols/commands/{commandId}/detail |
查看协议命令详情，并联查关联 node 命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
commandId（必填） |
GET /api/v2/protocols/commands/{commandId}/diagnosis |
查看单条协议命令的可解释诊断。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
commandId（必填） |
GET /api/v2/protocols/commands/diagnostics |
诊断协议命令失败和超时分布。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
errorOnly、analyzeLimit、bucketLimit、protocol、status、commandType、deviceId、channelId、nodeId、correlationId、requestedBy、from、to、sinceHours、keyword |
GET /api/v2/protocols/commands/stats |
统计协议命令运行状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
protocol、status、commandType、deviceId、channelId、nodeId、correlationId、requestedBy、from、to、sinceHours、keyword |
GET /api/v2/protocols/devices |
查询协议设备列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
page、pageSize、protocol、status、keyword |
POST /api/v2/protocols/devices |
保存协议设备。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
SaveProtocolDeviceRequest |
DELETE /api/v2/protocols/devices/{protocol}/{deviceId} |
清除待生成通道的协议设备。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
protocol（必填）、deviceId（必填） |
POST /api/v2/protocols/devices/{protocol}/{deviceId}/hard-delete |
物理删除未激活协议设备的历史残留。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
protocol（必填）、deviceId（必填）、HardDeletePendingProtocolDeviceRequest |
PUT /api/v2/protocols/devices/{protocol}/{deviceId}/name |
修改协议设备的平台展示名称。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>devices.manage |
protocol（必填）、deviceId（必填）、RenameProtocolDeviceRequest |
GET /api/v2/protocols/sessions |
统一查询 GB28181、ONVIF 等协议流会话。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
page、pageSize、protocol、sessionType、state、deviceId、channelId、mediaServerId、nodeId、app、stream、streamId、ssrc、rtpPort、from、to、sinceHours、keyword |
GET /api/v2/protocols/sessions/{sessionId} |
查看协议流会话详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
sessionId（必填） |
GET /api/v2/protocols/signals |
统一查询 GB28181、ONVIF 等协议信令事件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
protocol、eventType、deviceId、channelId、status、keyword、page、pageSize |
统一对讲
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/talk/sessions/{sessionId} |
查询对讲媒体发送状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>devices.view |
sessionId（必填） |
POST /api/v2/talk/sessions/{sessionId}/audio |
向已建立的 GB28181 或 ONVIF 对讲会话写入 G.711 音频。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>devices.talk |
sessionId（必填）、string |
DELETE /api/v2/talk/sessions/{sessionId}/media |
仅释放对讲媒体发送端。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>devices.talk |
sessionId（必填） |
POST /api/v2/talk/sessions/{sessionId}/ptt |
设置对讲会话 PTT 发送门控。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>devices.talk |
sessionId（必填）、TalkPushToTalkRequest |
接口字段与示例
本页故意先讲清业务用途，不把几百个字段塞进说明文字。真正编码时，请使用与部署版本一起提供的 OpenAPI 和 Postman 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。