VSS 视频流服务对接开发接口文档

面向开发者的 VSS API 描述文档。适用于第三方系统、大视景数字孪生平台 (DTS)、实施交付和运维团队对接 VSS 视频源接入、设备管理、服务管理、视频播放与控制能力。

文档信息

服务接口简介

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

本文档面向需要通过接口对接 VSS 的开发者，重点覆盖以下能力：

• 服务节点、后台进程和服务配置管理。
• 首页运行记录、媒体服务图表和运行状态查询。
• 视频源、设备、码流、快照、在线状态和组合设备管理。
• 播放会话创建、视频源/设备列表读取、实时播放、历史回放、云台控制、抓图和码流解码信息回调。

本文档描述的是 VSS 对接开发接口，不替代现场部署手册、账号权限开通流程、设备厂家 SDK 文档或具体项目的网络开通说明。涉及实际地址、Token、设备账号、第三方平台密钥、节点 GUID 等信息时，应以交付环境配置为准。

使用环境

接入准备

遵循的规范

认证与权限

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

Authorization: Bearer <access_token>
Content-Type: application/json

[!IMPORTANT]

1. 添加 Onvif、流媒体、本地/网盘视频文件、第三方平台等视频源时，摄像机密码、网盘连接密码、平台密钥、Token 等敏感信息不得在前端或日志中明文暴露。
2. 部分写操作接口可能触发后台异步任务、服务配置刷新或服务重启，请勿在高并发流量下频繁调用。

公共请求头

公共响应格式

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

{
  "code": 0,
  "message": "操作成功",
  "data": {},
  "requestId": "7f3f2f7a-4d4a-4b2f-9c5c-000000000000"
}

兼容说明：不同部署环境中业务数据字段名称可能为 data 或 info。对接时请优先读取 data 字段，若为空可回退读取 info 字段。

分页、过滤与排序

分页查询接口中，data 字段通常返回以下分页包装结构：

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

错误处理

通用错误码

错误响应示例

{
  "code": 2500001,
  "message": "参数校验失败",
  "data": null,
  "requestId": "7f3f2f7a-4d4a-4b2f-9c5c-000000000000"
}

调用限制

接口列表

HTTP 接口说明

服务节点管理模块

获取服务节点列表

查询 VSS 系统中注册的所有媒体网关服务节点列表。

请求参数说明

无

请求示例

POST /serviceNode/findNodeList

响应状态

200 OK

响应参数说明 (data 内部字段)

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

新增服务节点

注册并新增一台视频网关服务节点。

请求参数说明 (WatchdogServiceNode对象数组)

响应状态

200 OK

响应参数说明 (data 内部字段)

成功返回空值或操作提示。

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

修改服务节点

修改现有服务节点的信息。

请求参数说明 (WatchdogServiceNode对象数组)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

删除服务节点

注销删除指定的服务节点。

输入参数 (Query 参数)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

首页模块

获取进程执行记录

请求参数说明 (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"
    }
  ]
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

获取媒体服务折线图数据

请求参数说明 (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"
    }
  ]
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

服务管理模块

获取服务列表

请求参数说明 (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"
    }
  ]
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

添加服务

请求参数说明 (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"
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

编辑服务

请求参数说明 (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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

删除服务

输入参数 (Query 参数)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

服务设置/进程控制

请求参数说明

传入 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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

视频源管理模块

分页获取视频源列表

请求参数说明 (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"
      }
    ]
  }
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

添加/保存视频源

请求参数说明

传入 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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

视频源添加分发服务

请求参数说明 (SaveMediaServiceDTO)

响应状态

200 OK

响应参数说明

data 返回新创建的分发任务进程 ID 字符串。

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

删除视频源

输入参数 (Query 参数)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

设备管理模块

分页获取设备列表

请求参数说明 (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"
      }
    ]
  }
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

添加/修改设备

请求参数说明 (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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

批量更新设备信息

请求参数说明

传入 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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

批量删除设备

输入参数 (Query 参数)

响应状态

200 OK

请求示例

POST /mediaDevice/deleteMediaDevices?guids=dev_onvif_80_01,dev_hk_99_02

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

请求参数说明

传入 BatchUpdateDeviceSnapshotDTO 数组。

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

请求参数说明 (BatchUpdateDeviceStatusDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

获取设备媒体码流信息

输入参数 (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
    }
  ]
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

请求参数说明 (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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

设备合并模块

分页获取组合设备列表

请求参数说明 (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"
          }
        ]
      }
    ]
  }
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

自动合并设备操作

请求参数说明 (AutoCombinationDTO)

请求示例

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

响应状态

200 OK

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

手动批量添加组合设备

请求参数说明

传入 AddMediaCombinationDeviceDTO 数组。

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

批量解除组合设备

请求参数说明

传入需要解除组合的主设备 GUID 数组。

响应状态

200 OK

请求示例

[
  "comb_dev_001"
]

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

视频播放与控制模块

创建播放会话

在标准媒体服务上为当前播放客户端建立与该服务节点的取流交互会话，并返回流媒体网络通信及取流参数配置。

请求参数说明 (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
    }
  }
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

销毁播放会话

销毁指定的取流会话，断开其下所有视频通道的流连接并释放流媒体资源。

请求参数说明 (DestroySessionDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

获取与该会话连通的所有激活的视频源信息。

请求参数说明 (GetSessionMediaSourceDTO)

响应状态

200 OK

响应参数说明 (ReturnValue.mediaSourceList[] 内部字段)

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

查询该会话内指定视频源包含的子设备通道，常用于前端播放组件的通道资源展示与快速选定。

请求参数说明 (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
      }
    ]
  }
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

在特定会话下，向流媒体服务端请求开启对指定设备通道的拉流与推流分发，建立对应的实时/回放数据通道。

请求参数说明 (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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

停止播放与推流

停止当前播放会话的流媒体数据传输并断开推流连接。

请求参数说明 (StopPlayDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

球机控制 - 开始云台控制

对球机摄像机下发云台开始移动指令（如转动方向、变焦缩放、光圈对焦等）。

请求参数说明 (StartPtzDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

球机控制 - 停止云台控制

停止当前正在旋转或调整中的云台移动动作。

请求参数说明 (StopPtzDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

查询球机当前的水平转角 (Pan)、垂直角 (Tilt) 及变焦倍数 (Zoom)。

请求参数说明 (GetPtzPosDTO)

响应状态

200 OK

响应参数说明 (ReturnValue 内部字段)

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

驱动球机直接定位并精准转动到指定的 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
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

在视频历史录像回放模式下，控制当前数据传输流通道的暂停发送以及重新恢复启动，用以对接前端播放控制栏。

请求参数说明 (PlaybackControlDTO)

响应状态

200 OK

• 请求示例 (暂停回放):

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

快速跳转回放到视频通道中的任意毫秒级历史时间点重新开始推流。

请求参数说明 (SeekPlayDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

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

改变历史回放时的推流传输倍速。

请求参数说明 (SetSpeedDTO)

响应状态

200 OK

请求示例

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

响应示例

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

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

视频抓图

对播放中的指定通道视频帧进行实时抓图，服务端完成截图保存后，返回该张快照图片的 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"
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

播放码流解码信息回调

• 事件名称: 播放码流解码属性上报消息事件 (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
    }
  }
}

备注

• 写操作可能触发后台服务配置刷新、设备发现、进程控制或流媒体会话变化；生产环境调用前应确认执行窗口和影响范围。
• 涉及密码、密钥、Token、上游播放地址等敏感信息时，应由服务端加密或代理处理，不应在前端或日志中明文暴露。

WebSocket 与回调消息

VSS 播放链路中，HTTP 接口负责创建会话、获取视频源和设备列表、启动/停止播放、控制云台和历史回放；实际媒体数据通常由流媒体服务通过 WebSocket 或其他播放协议分发。

播放码流解码信息回调

播放过程中，流媒体服务可能上报码流解码参数，例如视频编码、分辨率、帧率、音频采样率等。字段说明见“播放码流解码信息回调”接口条目。

数据模型

CommonResponse

PageVO

ServiceNode

MediaSource

MediaDevice

PlaybackSession

典型调用流程

管理类接口调用流程

sequenceDiagram
  participant Client as 调用方
  participant IAM as IAM 认证网关
  participant VSS as VSS 业务 API
  Client->>IAM: 登录并获取 Bearer Token
  IAM-->>Client: 返回 Token
  Client->>VSS: 携带 Authorization 调用业务接口
  VSS-->>Client: 返回 CommonResponse / PageVO

视频源接入与设备发现流程

sequenceDiagram
  participant Client as 调用方
  participant VSS as VSS 业务 API
  participant Node as 服务节点 MediaManager
  Client->>VSS: 查询服务节点
  Client->>Node: createSession 创建媒体源会话
  Client->>Node: quickDiscoveryDevice / checkMediaDiscoveryTask
  Node-->>Client: 返回发现到的设备或资源
  Client->>VSS: saveMediaSource 保存视频源
  Client->>VSS: batchUpdateMediaDevice 写入设备列表
  Client->>VSS: findMediaDevicePage 验证设备结果

视频播放流程

sequenceDiagram
  participant Client as 播放端
  participant VSS as 播放控制接口
  participant Media as 流媒体服务
  Client->>VSS: StdMedia/createSession
  VSS-->>Client: 返回 streamServer 信息
  Client->>VSS: 获取视频源和设备列表
  Client->>VSS: StdMedia/startPlay
  VSS-->>Client: 返回播放地址或会话状态
  Client->>Media: 建立 WebSocket 播放连接
  Media-->>Client: 推送码流与解码信息回调
  Client->>VSS: stopPlay / destroySession

版本变更

Tags: #handbook #api #开发接口 #接口文档 #VSS #视频流服务