视频监控服务接入指南

一、接入前准备

1.1 硬件准备

在开始接入之前，您需要准备以下硬件：

项目	要求	说明
摄像头设备	支持萤石云协议的海康威视网络摄像机	推荐使用海康威视品牌，兼容性最佳
网络环境	设备需能连接互联网	船舶上需有4G/5G网络或卫星网络
电源供应	12V直流供电	确保航行期间持续供电

1.2 信息准备

接入过程中需要使用到以下关键信息：

信息项	获取方式	用途
设备序列号	设备包装标签或机身标签	唯一标识摄像头设备
设备验证码	设备机身标签	验证设备所有权
船舶MMSI	船舶九位识别码	将设备与船舶关联
船讯网账号	注册船讯网获得	登录绑定工具

二、获取API Key（授权码）

船讯网视频监控服务使用 API Key 进行身份认证和权限控制。获取流程如下：

步骤1：注册船讯网账号

访问船讯网官网（www.shipxy.com）

点击注册，使用手机号完成账号注册

已有船讯网账号的用户可直接登录

步骤2：创建应用Key

登录后进入API板块控制台中的 "应用管理" 模块

点击 "创建应用"，填写应用名称（如"视频监控服务"）

系统会自动生成一个 应用 Key（格式如 1F6D701272402D1E7D8D316CCE519123）

点击复制按钮，妥善保存该 Key

┌────────────────────────────────────────────────────────────────────┐
│  ⚠️  重要提示                                                       │
│                                                                    │
│  1. API Key 是调用服务的唯一凭证，请勿泄露给第三方                    │
│  2. 一个账户最多可注册 5 个应用 Key                                  │
│  3. 第一个 Key 具备初始测试权限，正式使用需联系商务开通更多权限       │
│  4. 如需视频监控服务权限，将 Key 发送给对接的销售人员即可             │
│                                                                    │
│  商务邮箱：support@shipxy.com | 电话：400-010-8558                  │
└────────────────────────────────────────────────────────────────────┘

步骤3：权限配置

不同的使用场景需要开通不同的接口权限：

使用场景	需开通的权限
基础视频查看	实时视频查看（默认开通）
设备状态监控	设备状态查询 + 事件查询
AI事件预警	事件推送订阅 + AI事件识别权限
历史数据回溯	历史视频 + 截图查询 + 视频下载
疑似偷盗监测	疑似偷盗事件识别（需单独开通）

三、设备入网与绑定

3.1 设备入网要求

监控设备需要通过 萤石云协议 添加到平台

如果设备已经被添加到其他萤石云平台，需要先将设备从其他平台删除

3.2 获取设备信息

方式一：查看设备标签（推荐）

大部分设备在机身背面或包装标签上印刷有设备序列号和验证码：
包装：

机身：

方式二：通过设备管理页面获取

将电脑与摄像头连接到同一局域网

打开浏览器，输入设备IP地址（如 http://192.168.1.64）

使用管理员账号登录设备管理页面

进入 配置 → 网络 → 设备接入 → 萤石云

启用萤石云，确认注册状态为"在线"

点击 账号绑定 → 设备二维码点击查看，获取设备二维码

注意：点击查看二维码后，请立即记录序列号和验证码。不要重复点击查看，因为每次查看都会刷新验证码，之前获取的验证码将失效。

3.3 绑定设备到船舶

登录绑定工具

打开绑定工具地址：https://setupv.shipxy.com

使用船讯网手机号和密码登录

支持PC端浏览器、微信等多种环境访问

绑定形式一：新增设备绑定

适用于设备首次绑定到船讯网平台。

前置条件：

设备已通电并联网

设备未在其他萤石云平台上绑定

操作步骤：

登录绑定工具后，点击 【新增】

输入 设备序列号

验证码默认填写 a12345678（如设备有特殊验证码，请按实际填写）

输入或搜索要绑定的 船名或MMSI

选择摄像头的 安装位置（位置选择很重要，关系到AI识别的准确性）

点击 【保存】

绑定成功后，点击 【实时视频】 查看画面，确认角度合适

安装位置说明：请根据摄像头实际安装位置选择，如"驾驶台"、"左舷"、"右舷"、"船艏"、"船艉"、"货舱"等。不同位置对应不同的AI识别策略。

绑定形式二：轮转设备绑定

适用于设备已经在船讯网平台中，需要更换绑定到不同的船舶。

特点：

不需要设备通电在线也能完成换绑

航次结束后可将设备收回，绑定到虚拟船舶等待下次使用

操作步骤：

登录绑定工具，选择 【轮转设备绑定】

输入 设备序列号，搜索并点击 【重新绑定】

输入或搜索新的 船名或MMSI

选择新的 安装位置

点击 【保存】

换绑成功后，新船舶的视频权限会自动添加到账号下

航次结束后的设备解绑

当航次结束，轮转摄像头被拆下寄回时，需要将设备与运输船舶解除绑定，统一转移到虚拟船舶上等待下次使用。

操作步骤：

收到拆下寄回的设备后，选择 【轮转设备绑定】

输入 设备序列号，搜索并点击 【重新绑定】

输入虚拟船舶 MMSI：414414414

点击 【保存】 即可

3.4 绑定验证

绑定完成后，请进行以下验证：

在船讯网APP或PC网页端查看是否能正常显示视频画面

检查视频画面角度是否合适，能否覆盖需要监控的区域

如果画面不清晰或角度不对，可现场调整摄像头位置后重新查看

四、API服务接入

4.1 接口调用方式

船讯网视频监控服务提供RESTful API接口，所有接口统一通过以下方式调用：

服务基地址： https://api.shipxy.com

认证方式： 通过URL参数传递API Key（授权码）

请求格式：

https://api.shipxy.com/apicall/v3/{接口名称}?key={您的API Key}&参数1=值1&参数2=值2

返回格式： 统一返回JSON格式数据

{
  "status": 0,      // 状态码，0表示成功
  "msg": "",        // 状态描述
  "data": { }       // 业务数据
}

4.2 权限开通

调用API接口前，需要确保您的API Key已开通对应的接口权限。权限开通流程：

准备好您的API Key

联系船讯网商务或销售人员（support@shipxy.com）

说明需要开通视频监控服务相关权限

商务人员会为您配置权限

权限开通后即可调用接口

4.3 接口分类

视频监控服务的API接口分为以下几类：

接口类别	说明	典型接口
设备查询类	查询船舶绑定的设备信息	GetShipDevicesStatus
视频查看类	获取实时/历史视频URL	GetVShipPreview、GetVShipPlayback
截图查询类	查询定时截图	GetVShipImgs
事件查询类	查询AI识别的事件记录	GetVShipAiEvents
视频下载类	创建和管理视频下载任务	AddPlaybackRecordTask等
事件订阅类	管理事件推送订阅	VShipSubscribeSet等

详细的接口定义和参数说明，请参考《船讯网视频监控API服务说明》文档。

五、事件推送接入

5.1 推送机制说明

船讯网视频监控服务支持将AI识别到的异常事件 实时推送 到客户指定的接收端。推送流程如下：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  船载摄像头  │────▶│  AI事件识别  │────▶│  事件推送   │
│  检测异常   │     │  触发告警   │     │  至客户系统  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                                        ┌──────┴──────┐
                                        │  电话通知    │
                                        │  (增值服务)  │
                                        └─────────────┘

5.2 订阅船舶事件

要接收某艘船舶的视频事件推送，需要先将该船舶添加到订阅列表中。

操作方式： 调用 VShipSubscribeSet 接口

必填参数：

key：您的API Key

mmsi：要订阅的船舶MMSI

可选参数：

cell：绑定手机号码，开通电话通知服务后，事件发生时将拨打此号码

返回说明：

添加成功：返回成功提示

添加失败：可能原因包括权限不足、订阅数量超限、船舶不在用户视频平台清单中

5.3 管理订阅列表

操作	接口	说明
添加订阅	VShipSubscribeSet	将船舶加入事件订阅列表
删除订阅	VShipSubscribeDel	将船舶从订阅列表中移除
查询列表	VShipSubscribeQuery	查看当前所有订阅的船舶

5.4 推送数据格式

事件推送的数据格式为JSON，包含以下关键字段：

字段	说明
ship_name	船舶名称
mmsi	船舶MMSI
device_name	视频设备名称和位置
type_name	事件类型（如"人员入侵"、"疑似偷盗"等）
event_time	事件发生时间（北京时间）
img_url	事件发生时自动截图的URL
position	事件发生的位置描述

疑似偷盗事件额外字段：

字段	说明
description	具体的偷盗子类型描述

5.5 电话通知服务（增值服务）

如需开通电话通知功能，请联系船讯网商务：

在订阅船舶时，通过 cell 参数绑定接收电话的手机号码

开通电话通知服务后，当船舶发生异常事件时

系统会自动对接外呼平台，拨打绑定的手机号码

电话中将语音播报事件类型和船舶信息

六、验证接入是否成功

完成以上接入步骤后，可以通过以下方式验证接入是否成功。

测试1：查询设备状态

调用接口： GetShipDevicesStatus

请求示例：

https://api.shipxy.com/apicall/v3/GetShipDevicesStatus?key=您的API Key&mmsi=船舶MMSI

验证标准：

如果返回设备列表（包含device_id、device_name、device_state），说明设备绑定成功

device_state为1表示设备在线，2表示离线

测试2：查看实时视频

调用接口： GetVShipPreview

请求示例：

https://api.shipxy.com/apicall/v3/GetVShipPreview?key=您的API Key&mmsi=船舶MMSI

验证标准：

如果返回一个H5页面的URL，在浏览器中打开能看到实时视频画面，说明视频服务正常

测试3：查询事件记录

调用接口： GetVShipAiEvents

请求示例：

https://api.shipxy.com/apicall/v3/GetVShipAiEvents?key=您的API Key&mmsi=船舶MMSI&start_time=开始时间戳&end_time=结束时间戳

验证标准：

如果返回事件列表（total字段大于0），说明AI事件识别服务正常

如果total为0，可能是该时间段内确实没有事件发生

常见问题排查

问题现象	可能原因	解决方法
查询不到设备	设备未绑定或绑定失败	重新登录绑定工具检查绑定状态
设备状态为离线	设备未通电或网络不通	检查设备电源和网络连接
无法查看视频	API Key没有视频权限	联系商务开通权限
查询不到事件	时间段内无事件或未开通AI权限	检查权限配置，更换时间段重试
收不到推送	船舶未加入订阅列表	调用订阅接口添加船舶

文档结束
详细的接口参数说明请参考《船讯网视频监控API服务说明》
如有疑问，请联系船讯网技术支持团队：service@shipxy.com | 400-010-8558

视频监控服务接入指南

目录#

一、接入前准备#

1.1 硬件准备#

1.2 信息准备#

二、获取API Key（授权码）#

步骤1：注册船讯网账号#

步骤2：创建应用Key#

步骤3：权限配置#

三、设备入网与绑定#

3.1 设备入网要求#

3.2 获取设备信息#

方式一：查看设备标签（推荐）#

方式二：通过设备管理页面获取#

3.3 绑定设备到船舶#

登录绑定工具#

绑定形式一：新增设备绑定#

绑定形式二：轮转设备绑定#

航次结束后的设备解绑#

3.4 绑定验证#

四、API服务接入#

4.1 接口调用方式#

4.2 权限开通#

4.3 接口分类#

五、事件推送接入#

5.1 推送机制说明#

5.2 订阅船舶事件#

5.3 管理订阅列表#

5.4 推送数据格式#

5.5 电话通知服务（增值服务）#

六、验证接入是否成功#

测试1：查询设备状态#

测试2：查看实时视频#

测试3：查询事件记录#

常见问题排查#

目录

一、接入前准备

1.1 硬件准备

1.2 信息准备

二、获取API Key（授权码）

步骤1：注册船讯网账号

步骤2：创建应用Key

步骤3：权限配置

三、设备入网与绑定

3.1 设备入网要求

3.2 获取设备信息

方式一：查看设备标签（推荐）

方式二：通过设备管理页面获取

3.3 绑定设备到船舶

登录绑定工具

绑定形式一：新增设备绑定

绑定形式二：轮转设备绑定

航次结束后的设备解绑

3.4 绑定验证

四、API服务接入

4.1 接口调用方式

4.2 权限开通

4.3 接口分类

五、事件推送接入

5.1 推送机制说明

5.2 订阅船舶事件

5.3 管理订阅列表

5.4 推送数据格式

5.5 电话通知服务（增值服务）

六、验证接入是否成功

测试1：查询设备状态

测试2：查看实时视频

测试3：查询事件记录

常见问题排查