VSS (视频监控服务) 服务对接开发接口文档

• 版本: v1.2.0
• 发布日期: 2026-05-28
• 对接说明: 本文档描述第三方系统如何对接与调用 VSS (视频监控服务 / Video Surveillance Service) 系统接口，以获取监控概览、管理与操作后台服务进程、配置视频源及关联的分发服务、管理设备及码流属性、配置设备合并、以及调用流媒体播放和球机/回放控制等。
• 适用范围: 适用于需要集成 VSS 监控资源管理能力的大视景数字孪生平台 (DTS) 开发人员或第三方集成商。

1. 前置说明

1.1 服务简介

VSS 是大视景科技自主研发的视频监控流服务系统，核心职责是接入各类视频源（NVR、网络摄像机、平台 SDK、本地/网盘视频文件等）、管理其子设备通道、分发音视频流并提供实时播放和控制服务。

1.2 服务节点与端口

• VSS 业务 API: 默认为 http://<VSS_Host>:38090（示例：http://192.168.100.37:38090）
• VSS 写入服务节点: 默认为 http://<VSS_Host>:9105
• 默认服务节点 GUID: 96EA-EF2647F2-64069F30-3E467FE12038

1.3 认证与鉴权方式

本 API 统一采用 Authorization 请求头进行身份验证。客户端在调用需要权限的接口时，应在 HTTP 请求头中携带合法的 Bearer Token。

Authorization: Bearer <Your-VSS-Token>

[!IMPORTANT]

1. 本服务对于添加 Onvif、流媒体、本地/网盘视频文件等功能，底层会对相关敏感数据（如摄像机密码、网盘连接密码）进行加密存储，接口的请求或响应中均不得以明文传输密码。
2. 部分写操作接口可能涉及后台异步服务的重新启动，请勿在高并发流量下频繁调用写接口。

2. 公共参数

2.1 全局请求头 (Headers)

2.2 公共响应格式

除数据导出等特殊接口外，本服务接口的标准返回体如下：

{
  "code": 0,
  "message": "操作成功",
  "data": {}
}

• code: 返回状态码，0 表示成功，非 0 表示发生异常或失败。常见错误码：2500001 参数校验失败，2500000 未知错误。
• message: 友好提示消息。
• data: 具体业务返回数据，可以是对象、数组或分页数据结构。

注意: 不同部署环境中该字段名称可能为 data 或 info，对接时请优先尝试 data 字段，若为空则回退读取 info 字段。

2.3 分页公共响应结构 (PageVO)

在分页查询接口中，data 字段固定为以下分页包装格式：

{
  "currentPage": 1,
  "pageSize": 10,
  "totalPage": 5,
  "totalRow": 48,
  "list": []
}

3. 接口列表 (按功能模块分类)

3.1 身份认证与权限管理

3.1.1 用户登录

• 接口名称: 用户登录
• 请求方式: POST
• URL: /openApi/internal/login
• Host: http://192.168.100.38:28080（IAM 统一认证网关）
• 请求参数说明 (LoginDTO):

• 响应状态: 200 OK
• 响应参数说明 (data 内部字段):

• 请求示例:

  {
    "account": "admin",
    "password": "123"
  }

• 响应示例:

  {
    "code": 0,
    "message": "登录成功",
    "data": "Bearer eyJhbGciOiJIUzI1NiIsIn..."
  }

3.1.2 退出登录

• 接口名称: 退出登录
• 请求方式: POST
• URL: /openApi/internal/logout
• Host: http://192.168.100.37:38090
• 接口描述: 注销当前用户的会话，使当前的 Bearer Token 失效。
• 请求参数说明: 无
• 请求示例:

  POST /openApi/internal/logout

• 响应状态: 200 OK
• 响应参数说明:

• 响应示例:

  {
    "code": 0,
    "message": "注销成功",
    "data": null
  }

3.1.3 获取当前用户信息

• 接口名称: 获取当前用户信息
• 请求方式: GET
• URL: /home/web_user
• Host: http://192.168.100.37:38090
• 接口描述: 获取当前已登录账户的详细基本信息（包含用户名、昵称、角色等属性）。
• 请求参数说明: 无 (从请求头中的 Authorization Token 自动解析)
• 请求示例:

  GET /home/web_user

• 响应状态: 200 OK
• 响应参数说明 (data 内部字段):

• 响应示例:

  {
    "code": 0,
    "message": "获取成功",
    "data": {
      "username": "admin",
      "nickName": "系统管理员",
      "role": "admin"
    }
  }

3.2 服务节点管理模块

3.2.1 获取服务节点列表

• 接口名称: 获取服务节点列表
• 请求方式: POST
• URL: /serviceNode/findNodeList
• Host: http://192.168.100.37:38090
• 接口描述: 查询 VSS 系统中注册的所有媒体网关服务节点列表。
• 请求参数说明: 无
• 请求示例:

  POST /serviceNode/findNodeList

• 响应状态: 200 OK
• 响应参数说明 (data 内部字段):

• 响应示例:

  {
    "code": 0,
    "message": "获取节点列表成功",
    "data": [
      {
        "guid": "96EA-EF2647F2-64069F30-3E467FE12038",
        "name": "默认服务节点",
        "uri": "http://192.168.100.235:9105"
      }
    ]
  }

3.2.2 新增服务节点

• 接口名称: 新增服务节点
• 请求方式: POST
• URL: /serviceNode/saveNode
• Host: http://192.168.100.37:38090
• 接口描述: 注册并新增一台视频网关服务节点。
• 请求参数说明 (WatchdogServiceNode对象数组):

• 响应状态: 200 OK
• 响应参数说明 (data 内部字段): 成功返回空值或操作提示。
• 请求示例:

  [
    {
      "name": "新服务节点-02",
      "uri": "http://192.168.100.236:9105"
    }
  ]

• 响应示例:

  {
    "code": 0,
    "message": "服务节点保存成功",
    "data": null
  }

3.2.3 修改服务节点

• 接口名称: 修改服务节点
• 请求方式: POST
• URL: /serviceNode/updateNode
• Host: http://192.168.100.37:38090
• 接口描述: 修改现有服务节点的信息。
• 请求参数说明 (WatchdogServiceNode对象数组):

• 响应状态: 200 OK
• 请求示例:

  [
    {
      "guid": "96EA-EF2647F2-64069F30-3E467FE12039",
      "name": "新服务节点-02-已修改",
      "uri": "http://192.168.100.236:9105"
    }
  ]

• 响应示例:

  {
    "code": 0,
    "message": "服务节点修改成功",
    "data": null
  }

  `

3.2.4 删除服务节点

• 接口名称: 删除服务节点
• 请求方式: POST
• URL: /serviceNode/deleteNode
• Host: http://192.168.100.37:38090
• 接口描述: 注销删除指定的服务节点。
• 输入参数 (Query 参数):

• 响应状态: 200 OK
• 请求示例:

  POST /serviceNode/deleteNode?guids=96EA-EF2647F2-64069F30-3E467FE12039

• 响应示例:

  {
    "code": 0,
    "message": "服务节点删除成功",
    "data": null
  }

3.3 首页模块

3.3.1 获取进程执行记录

• 接口名称: 获取运行进程执行记录
• 请求方式: POST
• URL: /home/findExecuteRecord
• Host: http://192.168.100.37:38090
• 请求参数说明 (GetExecuteRecordDTO):

• 响应状态: 200 OK
• 响应参数说明 (data 内部字段):

• 请求示例:

  {
    "date": "2026-05-28",
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
    "statusType": "running"
  }

• 响应示例:

  {
    "code": 0,
    "message": "获取执行记录成功",
    "data": [
      {
        "guid": 1298481,
        "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
        "processGuid": "FD296E9D-47C2-4B9B-BFC6-78739C351AFF",
        "instanceId": "proc_inst_901",
        "statusType": "running",
        "executeRecord": {},
        "addTime": "2026-05-28T09:00:00.000Z"
      }
    ]
  }

3.3.2 获取媒体服务折线图数据

• 接口名称: 获取 MediaService 监控折线图数据
• 请求方式: POST
• URL: /home/findMediaServiceChart
• Host: http://192.168.100.37:38090
• 请求参数说明 (GetMediaServiceChartDTO):

• 请求示例:

  {
    "date": "2026-05-28",
    "interval": 5,
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038"
  }

• 响应状态: 200 OK
• 响应示例:

  {
    "code": 0,
    "message": "获取折线图数据成功",
    "data": [
      {
        "guid": 1298482,
        "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
        "processGuid": "FD296E9D-47C2-4B9B-BFC6-78739C351AFF",
        "instanceId": "proc_inst_chart_01",
        "statusType": "active",
        "executeRecord": {
          "cpuUsage": "12.5%",
          "memoryUsage": "256MB",
          "streamRequestCount": 15,
          "streamDistributeCount": 42
        },
        "addTime": "2026-05-28T09:05:00.000Z"
      }
    ]
  }

3.4 服务管理模块

3.4.1 获取服务列表

• 接口名称: 获取服务节点下进程服务列表
• 请求方式: POST
• URL: /process/findProcessList
• Host: http://192.168.100.37:38090
• 请求参数说明 (GetProcessListDTO):

• 请求示例:

  {
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
    "softwareGuid": "soft-zlm-01",
    "usage": 1
  }

• 响应状态: 200 OK
• 响应示例:

  {
    "code": 0,
    "message": "获取服务列表成功",
    "data": [
      {
        "guid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D",
        "name": "ZLM流媒体服务网关",
        "status": 1,
        "usage": 1,
        "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038"
      }
    ]
  }

3.4.2 添加服务

• 接口名称: 添加服务进程配置
• 请求方式: POST
• URL: /process/saveProcess
• Host: http://192.168.100.37:38090
• 请求参数说明 (WatchdogProcess对象):

• 响应状态: 200 OK
• 响应参数说明: data 返回新添加服务的 guid 标识。
• 请求示例:

  {
    "name": "ZLM流媒体转发测试",
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
    "softwareGuid": "soft-zlm-01",
    "startTypes": 6,
    "instanceNums": 1,
    "keepAliveDelaySeconds": 3,
    "options": "--port 8080",
    "tag": "zlm-stream"
  }

• 响应示例:

  {
    "code": 0,
    "message": "服务添加成功",
    "data": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D"
  }

3.4.3 编辑服务

• 接口名称: 编辑修改服务配置
• 请求方式: POST
• URL: /process/updateProcess
• Host: http://192.168.100.37:38090
• 请求参数说明 (WatchdogProcess对象): 包含字段与 添加服务 接口一致，但必须提供服务的 guid 标识。

• 请求示例:

  {
    "guid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D",
    "name": "ZLM流媒体转发测试-修改",
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
    "startTypes": 6,
    "options": "--port 8081"
  }

• 响应状态: 200 OK
• 响应示例:

  {
    "code": 0,
    "message": "服务编辑修改成功",
    "data": null
  }

3.4.4 删除服务

• 接口名称: 删除服务进程
• 请求方式: POST
• URL: /process/deleteProcess
• Host: http://192.168.100.37:38090
• 输入参数 (Query 参数):

• 响应状态: 200 OK
• 请求示例:

  POST /process/deleteProcess?processGuid=5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D

• 响应示例:

  {
    "code": 0,
    "message": "服务删除成功",
    "data": null
  }

3.4.5 服务设置/进程控制

• 接口名称: 服务/进程配置与操作设置
• 请求方式: POST
• URL: /process/processSetup
• Host: http://192.168.100.37:38090
• 请求参数说明: 传入 ProcessSetupDTO 数组。

• 请求示例:

  [
    {
      "guid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D",
      "contextGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
      "configGuid": "config-zlm-template",
      "data": {
        "action": "restart"
      }
    }
  ]

• 响应状态: 200 OK
• 响应示例:

  {
    "code": 0,
    "message": "服务设置已成功下发并执行",
    "data": null
  }

3.5 视频源管理模块

3.5.1 分页获取视频源列表

• 接口名称: 分页获取视频源列表
• 请求方式: POST
• URL: /mediaSource/findMediaSourcePage
• Host: http://192.168.100.37:38090
• 请求参数说明 (GetMediaSourcePageDTO):

• 请求示例:

  {
    "currentPage": 1,
    "pageSize": 10,
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038",
    "driver": "onvif"
  }

• 响应状态: 200 OK
• 响应参数说明 (list[] 内部 MediaSourceBrief对象 关键字段):

• 响应示例:

  {
    "code": 0,
    "message": "获取视频源列表成功",
    "data": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPage": 1,
      "totalRow": 1,
      "list": [
        {
          "guid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
          "name": "自然语言测试_ONVIF_192_168_100_80",
          "driver": "onvif",
          "uri": "?combination=true",
          "deviceCount": 2,
          "processCount": 1,
          "status": 1,
          "context": "96EA-EF2647F2-64069F30-3E467FE12038",
          "extendData": "&accessMode=combination",
          "addTime": "2026-05-28T09:10:00.000Z",
          "updateTime": "2026-05-28T09:12:00.000Z"
        }
      ]
    }
  }

3.5.2 添加/保存视频源

• 接口名称: 保存添加视频源配置
• 请求方式: POST
• URL: /mediaSource/saveMediaSource
• Host: http://192.168.100.37:38090
• 请求参数说明: 传入 MediaSourceBrief对象 数组。

• 响应状态: 200 OK
• 请求示例:

  [
    {
      "guid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
      "name": "自然语言测试_本地视频文件夹_www_wwwroot",
      "driver": "local",
      "uri": "/www/wwwroot",
      "context": "96EA-EF2647F2-64069F30-3E467FE12038",
      "extendData": "freeKeepInterval=-1&accessMode=direct",
      "sourceTag": "local",
      "resourceType": 1
    }
  ]

• 响应示例:

  {
    "code": 0,
    "message": "视频源保存成功",
    "data": null
  }

3.5.3 视频源添加分发服务

• 接口名称: 为视频源添加/绑定流分发服务
• 请求方式: POST
• URL: /mediaSource/saveMediaService
• Host: http://192.168.100.37:38090
• 请求参数说明 (SaveMediaServiceDTO):

• 响应状态: 200 OK
• 响应参数说明: data 返回新创建的分发任务进程 ID 字符串。
• 请求示例:

  {
    "mediaSourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038"
  }

• 响应示例:

  {
    "code": 0,
    "message": "视频源分发服务添加成功",
    "data": "proc-dist-zlm-01"
  }

3.5.4 删除视频源

• 接口名称: 批量删除视频源
• 请求方式: POST
• URL: /mediaSource/deleteMediaSource
• Host: http://192.168.100.37:38090
• 输入参数 (Query 参数):

• 响应状态: 200 OK
• 请求示例:

  POST /mediaSource/deleteMediaSource?guids=0362659D-81CE-4A0D-A5FA-825C8D92FF4F

• 响应示例:

  {
    "code": 0,
    "message": "视频源已成功删除，关联的发现任务已完全注销",
    "data": null
  }

3.6 设备管理模块

3.6.1 分页获取设备列表

• 接口名称: 分页获取设备通道列表
• 请求方式: POST
• URL: /mediaDevice/findMediaDevicePage
• Host: http://192.168.100.37:38090
• 请求参数说明 (GetMediaDevicePageDTO):

• 请求示例:

  {
    "currentPage": 1,
    "pageSize": 10,
    "mediaSourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F"
  }

• 响应状态: 200 OK
• 响应参数说明 (list[] 内部 MediaDeviceBrief对象 关键字段):

• 响应示例:

  {
    "code": 0,
    "message": "获取设备列表成功",
    "data": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPage": 1,
      "totalRow": 1,
      "list": [
        {
          "guid": "dev_onvif_80_01",
          "viewName": "北京大门入口球机(大门入口球机)",
          "name": "dome_camera_ch1",
          "deviceType": 2,
          "uri": "192.168.100.80?username=admin&port=80",
          "status": 1,
          "sourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
          "extendData": "NetworkState=1&ClientDeviceTag=client-uuid-01",
          "addTime": "2026-05-28T09:12:00.000Z"
        }
      ]
    }
  }

3.6.2 添加/修改设备

• 接口名称: 添加或修改单个通道设备
• 请求方式: POST
• URL: /mediaDevice/updateMediaDevice
• Host: http://192.168.100.37:38090
• 请求参数说明 (UpdateMediaDeviceDTO):

• 响应状态: 200 OK
• 请求示例 (新增设备):

  {
    "viewName": "办公区通道摄像机",
    "deviceType": 1,
    "deviceModel": "DH-IPC-HFW1230S",
    "serialNumber": "SN-DH88901238",
    "spacePosition": "116.402,39.912",
    "extendData": "&SynchronizerGroupGuid=group-twin-01"
  }

• 响应示例:

  {
    "code": 0,
    "message": "设备保存成功",
    "data": null
  }

3.6.3 批量更新设备信息

• 接口名称: 批量修改更新设备属性
• 请求方式: POST
• URL: /mediaDevice/batchUpdateMediaDevice
• Host: http://192.168.100.37:38090
• 请求参数说明: 传入 BatchUpdateMediaDeviceDTO 数组。

• 响应状态: 200 OK
• 请求示例:

  [
    {
      "guid": "dev_onvif_80_01",
      "factoryGuid": "FAC-DEV-109",
      "viewName": "大门外球机-修改",
      "deviceType": 2,
      "sourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
      "extendData": "NetworkState=1&ClientDeviceTag=client-uuid-01"
    }
  ]

• 响应示例:

  {
    "code": 0,
    "message": "批量更新设备属性成功",
    "data": null
  }

3.6.4 批量删除设备

• 接口名称: 批量删除设备
• 请求方式: POST
• URL: /mediaDevice/deleteMediaDevices
• Host: http://192.168.100.37:38090
• 输入参数 (Query 参数):

• 响应状态: 200 OK
• 请求示例:

  POST /mediaDevice/deleteMediaDevices?guids=dev_onvif_80_01,dev_hk_99_02

• 响应示例:

  {
    "code": 0,
    "message": "所选设备已批量删除成功",
    "data": null
  }

3.6.5 批量更新设备快照 (获取/配置快照图像)

• 接口名称: 批量更新配置设备快照图像地址
• 请求方式: POST
• URL: /mediaDevice/batchUpdateDeviceSnapshot
• Host: http://192.168.100.37:38090
• 请求参数说明: 传入 BatchUpdateDeviceSnapshotDTO 数组。

• 响应状态: 200 OK
• 请求示例:

  [
    {
      "deviceGuid": "dev_onvif_80_01",
      "snapshotUri": "/snapshots/snap_80_01.jpg"
    }
  ]

• 响应示例:

  {
    "code": 0,
    "message": "批量更新设备快照成功",
    "data": null
  }

3.6.6 批量更新设备状态 (检测状态/码流在线情况)

• 接口名称: 批量更新并反馈设备运行与在线状态
• 请求方式: POST
• URL: /mediaDevice/batchUpdateDeviceStatus
• Host: http://192.168.100.37:38090
• 请求参数说明 (BatchUpdateDeviceStatusDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
    "deviceInfos": [
      {
        "deviceGuid": "dev_onvif_80_01",
        "state": 1
      }
    ]
  }

• 响应示例:

  {
    "code": 0,
    "message": "状态检测及更新更新成功",
    "data": null
  }

3.6.7 获取设备媒体码流信息

• 接口名称: 获取单台设备的媒体流通道属性
• 请求方式: POST
• URL: /mediaDevice/findMediaStreamBrief
• Host: http://192.168.100.37:38090
• 输入参数 (Query 参数):

• 响应状态: 200 OK
• 响应参数说明 (data 内部 MediaStreamBrief对象 关键字段):

• 请求示例:

  POST /mediaDevice/findMediaStreamBrief?guid=dev_onvif_80_01

• 响应示例:

  {
    "code": 0,
    "message": "获取媒体流信息成功",
    "data": [
      {
        "guid": "stream_01_main",
        "deviceGuid": "dev_onvif_80_01",
        "sourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
        "name": "主码流",
        "uri": "rtsp://192.168.100.80:554/h264/ch1/main/av_stream",
        "streamHint": 1,
        "videoCodecId": 28,
        "videoWidth": 1920,
        "videoHeight": 1080,
        "videoFrameRate": 25,
        "playType": 1,
        "audioCodecId": 0
      }
    ]
  }

3.6.8 批量编辑设备媒体码流信息

• 接口名称: 批量修改更新设备挂载的码流属性
• 请求方式: POST
• URL: /mediaDevice/batchUpdateMediaStreamBrief
• Host: http://192.168.100.37:38090
• 请求参数说明 (BatchUpdateMediaStreamBriefDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
    "deviceGuids": [
      "dev_onvif_80_01"
    ],
    "mediaStreamBriefInfos": [
      {
        "name": "主码流-修改",
        "streamHint": 1,
        "uri": "rtsp://192.168.100.80:554/modified_stream",
        "videoCodecId": 174,
        "videoWidth": 1920,
        "videoHeight": 1080,
        "videoFrameRate": 30,
        "playType": 1
      }
    ]
  }

• 响应示例:

  {
    "code": 0,
    "message": "批量编辑码流成功",
    "data": null
  }

3.7 设备合并模块

3.7.1 分页获取组合设备列表

• 接口名称: 分页获取已合并的组合设备列表
• 请求方式: POST
• URL: /mediaCombinationDevice/findPage
• Host: http://192.168.100.37:38090
• 请求参数说明 (GetMediaCombinationDevicePageDTO):

• 请求示例:

  {
    "currentPage": 1,
    "pageSize": 10,
    "nodeGuid": "96EA-EF2647F2-64069F30-3E467FE12038"
  }

• 响应状态: 200 OK
• 响应参数说明 (list[] 内部 MediaCombinationDeviceBrief对象 关键字段):

• 响应示例:

  {
    "code": 0,
    "message": "获取组合设备成功",
    "data": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPage": 1,
      "totalRow": 1,
      "list": [
        {
          "guid": "comb_dev_001",
          "viewName": "环岛公路十字路口综合监控",
          "deviceType": 1,
          "sourceGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
          "subMediaDeviceBriefs": [
            {
              "guid": "dev_hk_99_02",
              "viewName": "南门向东枪机",
              "status": 1,
              "sourceGuid": "ADBCE8A3-64AC-EB42-BD50-0F7C3808FDC7"
            }
          ]
        }
      ]
    }
  }

3.7.2 自动合并设备操作

• 接口名称: 自动规则匹配合并设备
• 请求方式: POST
• URL: /mediaCombinationDevice/autoCombination
• Host: http://192.168.100.37:38090
• 请求参数说明 (AutoCombinationDTO):

• 请求示例:

  {
    "mainGuid": "0362659D-81CE-4A0D-A5FA-825C8D92FF4F",
    "subGuids": [
      "ADBCE8A3-64AC-EB42-BD50-0F7C3808FDC7"
    ]
  }

• 响应状态: 200 OK
• 响应示例:

  {
    "code": 0,
    "message": "自动合并分析与写入成功",
    "data": null
  }

3.7.3 手动批量添加组合设备

• 接口名称: 手动绑定并添加组合设备
• 请求方式: POST
• URL: /mediaCombinationDevice/batchAdd
• Host: http://192.168.100.37:38090
• 请求参数说明: 传入 AddMediaCombinationDeviceDTO 数组。

• 响应状态: 200 OK
• 请求示例:

  [
    {
      "mainGuid": "comb_dev_001",
      "subGuids": [
        "dev_hk_99_02"
      ]
    }
  ]

• 响应示例:

  {
    "code": 0,
    "message": "组合绑定配置保存成功",
    "data": null
  }

3.7.4 批量解除组合设备

• 接口名称: 解除合并设备通道关系
• 请求方式: POST
• URL: /mediaCombinationDevice/batchRescission
• Host: http://192.168.100.37:38090
• 请求参数说明: 传入需要解除组合的主设备 GUID 数组。

• 响应状态: 200 OK
• 请求示例:

  [
    "comb_dev_001"
  ]

• 响应示例:

  {
    "code": 0,
    "message": "所选设备的组合合并关系已完全解除",
    "data": null
  }

3.8 视频播放与控制模块

3.8.1 创建播放会话

• 接口名称: 创建播放会话 (createSession)
• 请求方式: POST
• URL: /scriptFunction/StdMedia/createSession
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 在标准媒体服务上为当前播放客户端建立与该服务节点的取流交互会话，并返回流媒体网络通信及取流参数配置。
• 请求参数说明 (CreateSessionDTO):

• 响应状态: 200 OK
• 响应参数说明 (ReturnValue 内部字段):

• 请求示例:

  {
    "sessionID": "c76e2730-8a58-47e1-8888-de882b3d30b2"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": {
      "streamServer": {
        "protocols": [
          "ws"
        ],
        "address": "192.168.100.47",
        "streamPort": 9305
      }
    }
  }

3.8.2 销毁播放会话

• 接口名称: 销毁播放会话 (destroySession)
• 请求方式: POST
• URL: /scriptFunction/StdMedia/destroySession
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 销毁指定的取流会话，断开其下所有视频通道的流连接并释放流媒体资源。
• 请求参数说明 (DestroySessionDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "c76e2730-8a58-47e1-8888-de882b3d30b2"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.3 获取会话对应的视频源列表

• 接口名称: 获取会话对应的视频源列表 (getMediaSourceList)
• 请求方式: POST
• URL: /scriptFunction/StdMedia/getMediaSourceList
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 获取与该会话连通的所有激活的视频源信息。
• 请求参数说明 (GetSessionMediaSourceDTO):

• 响应状态: 200 OK
• 响应参数说明 (ReturnValue.mediaSourceList[] 内部字段):

• 请求示例:

  {
    "sessionID": "c76e2730-8a58-47e1-8888-de882b3d30b2"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": {
      "mediaSourceList": [
        {
          "mediaSourceName": "本地视频源",
          "mediaSourceGuid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D"
        }
      ]
    }
  }

3.8.4 获取视频源的下属设备通道

• 接口名称: 获取视频源的下属设备通道 (getDeviceList)
• 请求方式: POST
• URL: /scriptFunction/StdMedia/getDeviceList
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 查询该会话内指定视频源包含的子设备通道，常用于前端播放组件的通道资源展示与快速选定。
• 请求参数说明 (GetSessionDeviceListDTO):

• 响应状态: 200 OK
• 响应参数说明 (ReturnValue.mediaDeviceList[] 内部字段):

• 请求示例:

  {
    "sessionID": "c76e2730-8a58-47e1-8888-de882b3d30b2",
    "sourceGuid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D",
    "pageNo": 0,
    "pageSize": 1000
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": {
      "mediaDeviceList": [
        {
          "deviceGuid": "dev_local_001",
          "deviceName": "新东门外枪机.mp4",
          "viewName": "新东门外枪机",
          "deviceType": 1
        }
      ]
    }
  }

3.8.5 开启推流与获取流播放地址

• 接口名称: 开启播放推流并获取视频流数据地址 (startPlay)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/startPlay
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 在特定会话下，向流媒体服务端请求开启对指定设备通道的拉流与推流分发，建立对应的实时/回放数据通道。
• 请求参数说明 (StartPlayDTO):

• 流地址寻址与传输说明:
  • 调用本接口成功在流媒体端启动推流任务后，播放端可通过 WebSocket 协议直连建立二进制播放连接：
    ws://<streamServer.address>:<streamServer.streamPort>/<sessionID> （例如 ws://192.168.100.47:9305/player-session-001）。
  • 连接建立成功后，流媒体服务会将该通道解析出的原始 H.264/H.265/AAC 编码流以 ArrayBuffer 形式向 WebSocket 客户端实时持续推送，无需客户端另行轮询拉取。
• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001",
    "sourceGuid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D",
    "deviceGuid": "dev_local_001",
    "streamHint": "1",
    "playType": 1,
    "timeout": 30000
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.6 停止播放与推流

• 接口名称: 停止播放与推流 (stopPlay)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/stopPlay
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 停止当前播放会话的流媒体数据传输并断开推流连接。
• 请求参数说明 (StopPlayDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.7 球机控制 - 开始云台控制

• 接口名称: 开始云台控制 (startPtz)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/startPtz
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 对球机摄像机下发云台开始移动指令（如转动方向、变焦缩放、光圈对焦等）。
• 请求参数说明 (StartPtzDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001",
    "ptzCmd": 1,
    "ptzSpeed": 4,
    "ptzPriority": 1,
    "ptzLockTimeout": 5
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.8 球机控制 - 停止云台控制

• 接口名称: 停止云台控制 (stopPtz)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/stopPtz
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 停止当前正在旋转或调整中的云台移动动作。
• 请求参数说明 (StopPtzDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001",
    "ptzCmd": 1,
    "ptzPriority": 1
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.9 球机控制 - 获取云台绝对坐标

• 接口名称: 获取云台三维空间绝对坐标 (getPtzPos)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/getPtzPos
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 查询球机当前的水平转角 (Pan)、垂直角 (Tilt) 及变焦倍数 (Zoom)。
• 请求参数说明 (GetPtzPosDTO):

• 响应状态: 200 OK
• 响应参数说明 (ReturnValue 内部字段):

• 请求示例:

  {
    "sessionID": "player-session-001"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": "120.5 45.2 2.0"
  }

3.8.10 球机控制 - 设置云台绝对坐标

• 接口名称: 设置并跳转云台绝对位置 (setPtzPos)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/setPtzPos
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 驱动球机直接定位并精准转动到指定的 PTZ 三维空间坐标位置。
• 请求参数说明 (SetPtzPosDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001",
    "ptzPos": "120.5 45.2 2.0",
    "ptzSpeed": 4,
    "ptzPriority": 1,
    "ptzLockTimeout": 5
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.11 视频回放控制 - 暂停与恢复历史回放

• 接口名称: 暂停或恢复历史视频流的推送 (pausePlay / resumePlay)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/pausePlay (暂停) 或 /scriptFunction/WebSocketStream/resumePlay (恢复)
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 在视频历史录像回放模式下，控制当前数据传输流通道的暂停发送以及重新恢复启动，用以对接前端播放控制栏。
• 请求参数说明 (PlaybackControlDTO):

• 响应状态: 200 OK
• 请求示例 (暂停回放):

  {
    "sessionID": "player-session-001"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.12 视频回放控制 - 跳转播放时间点

• 接口名称: 历史回放跳转播放 (seekPlay)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/seekPlay
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 快速跳转回放到视频通道中的任意毫秒级历史时间点重新开始推流。
• 请求参数说明 (SeekPlayDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001",
    "time": 1716912000000
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.13 视频回放控制 - 历史回放倍速设定

• 接口名称: 修改历史回放的传输与播放速率 (setSpeed)
• 请求方式: POST
• URL: /scriptFunction/WebSocketStream/setSpeed
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 改变历史回放时的推流传输倍速。
• 请求参数说明 (SetSpeedDTO):

• 响应状态: 200 OK
• 请求示例:

  {
    "sessionID": "player-session-001",
    "speed": 2.0
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": null
  }

3.8.14 视频抓图

• 接口名称: 实时视频通道图像抓拍 (captureImage)
• 请求方式: POST
• URL: /scriptFunction/StdMedia/captureImage
• Host: 见取流服务 Http 地址 (示例: http://192.168.100.47:9305)
• 接口描述: 对播放中的指定通道视频帧进行实时抓图，服务端完成截图保存后，返回该张快照图片的 HTTP 下载/访问地址。
• 请求参数说明 (CaptureImageDTO):

• 响应状态: 200 OK
• 响应参数说明 (ReturnValue 内部字段):

• 请求示例:

  {
    "sessionID": "c76e2730-8a58-47e1-8888-de882b3d30b2",
    "sourceGuid": "5B7BE8B7-82E9-FB4B-BC17-02691BAEAD2D",
    "deviceGuid": "dev_local_001",
    "streamHint": "1"
  }

• 响应示例:

  {
    "Result": 0,
    "Message": "Success",
    "ReturnValue": "http://192.168.100.47:9305/snapshot/capture_dev_local_001.jpg"
  }

3.8.15 播放码流解码信息回调

• 事件名称: 播放码流解码属性上报消息事件 (CmdReportDecodeMediaParams)
• 触发时机: 当客户端播放器加载取流成功、启动 Wasm 解码并解析出音视频的首帧元数据时，解码器模块（bigview_decoder.js Web Worker）将以事件消息向前端应用发送当前播放的音视频详细封装与码流规格。
• 消息参数详情 (CmdReportDecodeMediaParams):

• 消息示例:

  {
    "cmd": 128,
    "params": {
      "video": {
        "index": 0,
        "codecID": 174,
        "width": 1920,
        "height": 1080,
        "decodePixelFormat": 0,
        "frameRate": 25
      },
      "audio": {
        "index": 1,
        "codecID": 86017,
        "sampleFormat": 0,
        "channels": 2,
        "sampleRate": 44100
      }
    }
  }

4. 附录

4.1 开发调试与连通性验证步骤

1. 获取服务状态: 通过调用 /process/findProcessList 确认 ZLM流媒体服务网关 等核心必备进程处于在线运行状态（status 为 1）。
2. 连接发现流程:
   • 对于添加本地视频文件夹，调用 saveMediaSource 并将 driver 设为 local，通过 URI 直接指定服务器端的本地绝对路径。
   • 对于添加网络文件夹源，将 driver 设为 netdisk，并通过 URI 参数形式传递加密后的连接凭证。
3. 验证同步: 通过 /mediaDevice/findMediaDevicePage 分页获取被发现出的视频通道列表，核对设备名称与在线状态。
4. 视频取流播放与控制验证:
   • 首先利用 StdMedia/createSession 获取可用节点取流 IP 和端口，确认标准流媒体网关已成功初始化。
   • 利用 WebSocketStream/startPlay 下发设备 GUID 开启取流与推流；前端播放器连接 ws://<IP>:<Port>/<SessionID> 开始拉流并上报 CmdReportDecodeMediaParams 验证码流帧规格。
   • 利用云台控制 startPtz/stopPtz/getPtzPos/setPtzPos 验证球机绝对定位偏转功能正常。

4.2 更新记录