船讯网视频监控API服务说明

文档版本：V1.0
适用版本：船讯网 API V3.0+
更新日期：2026-07-10
技术支持：service@shipxy.com | 400-010-8558

一、接口规范说明

1.1 通信协议

项目	说明
协议	HTTPS
数据格式	JSON
编码方式	UTF-8
请求方式	GET / POST

1.2 服务基地址

https://api.shipxy.com

1.3 认证方式

所有接口通过URL参数传递API Key（授权码）进行身份认证：

参数名	类型	必填	说明
key	string	是	船讯网授权码，验证服务权限

1.4 通用返回结构

{
  "status": 0,      // 状态码，0表示成功，其他表示失败
  "msg": "",        // 状态描述信息
  "data": { }       // 业务数据（具体结构因接口而异）
}

1.5 通用请求头

请求头	值	说明
Content-Type	application/json	JSON数据格式
Accept	application/json	接收JSON格式响应

二、设备状态查询接口

2.1 查询船舶视频设备状态

查询船舶当前绑定的视频设备列表及设备在线/离线状态。

说明：只能查询用户视频平台中已关联的船舶，未关联的船舶不会返回设备信息。

请求地址

服务地址	请求方式
`/apicall/v3/GetShipDevicesStatus`	GET

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	uint32	是	船舶MMSI编号，9位数字

请求示例

GET https://api.shipxy.com/apicall/v3/GetShipDevicesStatus?key=您的API Key&mmsi=413904861

返回参数

参数名	名称	类型	说明
ship_data	船舶信息	object	船舶基础信息
ship_data.mmsi	船舶MMSI	uint32	船舶MMSI编号
ship_data.ship_name	船舶名称	string	船舶英文名称
ship_data.ship_cnname	船舶中文名称	string	船舶中文名称
device_data	设备信息	array	设备列表，未绑定设备时为空数组
device_data[].device_id	设备序列号	string	视频设备序列号
device_data[].device_name	设备名称	string	视频设备安装位置描述
device_data[].device_state	设备状态	byte	1=正常运行，2=离线

返回示例

{
  "status": 0,
  "msg": "",
  "data": {
    "mmsi": 413904861,
    "ship_name": "粤新会货8233",
    "device_data": [
      {
        "device_id": "FE9129884",
        "device_name": "驾驶台",
        "device_state": 2
      },
      {
        "device_id": "FM5047354",
        "device_name": "驾驶台",
        "device_state": 1
      },
      {
        "device_id": "FM5047577",
        "device_name": "左舷",
        "device_state": 1
      }
    ]
  }
}

三、实时视频查看接口

3.1 获取船舶实时视频

获取船舶实时视频H5页面URL，可在浏览器中直接播放。

请求地址

服务地址	请求方式
`/apicall/v3/GetVShipPreview`	GET

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	uint32	是	船舶MMSI编号，9位数字

请求示例

GET https://api.shipxy.com/apicall/v3/GetVShipPreview?key=您的API Key&mmsi=413904861

返回参数

参数名	名称	类型	说明
data	视频预览URL	string	实时视频H5页面访问地址

返回示例

{
  "status": 0,
  "msg": "",
  "data": "https://v-api.shipxy.com/?p=k29HNJS83wATVFua1kh-KHEh0kDlxMHqgjcv-2bhEhDDVi5NfovLvfeMZb_4tFvapgQnhS_zMW7g4giwP_NCz5XEyKy7Ej8KPMa2xAW2OYQbOeJb4xVsghTLi6bQyhC_&sign=006c21c59eb14642fcc2cb0f18474cd31e4b9a29"
}

使用说明：将返回的URL在浏览器或WebView中打开即可查看实时视频画面。URL包含签名信息，具有一定有效期，过期后需要重新调用接口获取。

四、历史视频查看接口

4.1 获取船舶历史视频

查询摄像头指定时间段的历史视频，返回H5播放页面URL。

请求地址

服务地址	请求方式
`/apicall/v3/GetVShipPlayback`	GET

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	uint32	是	船舶MMSI编号，9位数字
start_time	开始时间	int	是	Unix时间戳，历史视频不超过2个月
end_time	结束时间	int	是	Unix时间戳，单次查询时间间隔不超过1个月

请求示例

GET https://api.shipxy.com/apicall/v3/GetVShipPlayback?key=您的API Key&mmsi=413904861&start_time=1751334377&end_time=1751939177

返回参数

参数名	名称	类型	说明
data	视频预览URL	string	历史视频H5页面访问地址

返回示例

{
  "status": 0,
  "msg": "",
  "data": "https://v-api.shipxy.com/?p=QaDqxL0mt37wqdCxJghRFyhUxIV75UhIq4S5LVY5sbtqqMHt0T8fIlBv2-FmdqDGTVqnJH__FQ58lN6EcdZ_gBNS7RXgc9FV3zrO57GTDFcd20sTdP5nYlYDFcPlJA-Svy_c9c9P-JuOwYFNkOZoWXHAyvdocqRkC6xYIEuOn-Q=&sign=2a6c2fa42476ec918b64dbf5c413df3567c92f2b"
}

五、定时截图查询接口

5.1 查询船舶定时截图

查询摄像头在指定时间段内自动截取的图片。系统每15-20分钟自动截图一次，可查询1年以内的截图信息。

请求地址

服务地址	请求方式	备注
`/apicall/v3/GetVShipImgs`	GET	15-20分钟自动截图一次，可查询1年以内的截图信息

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	uint32	是	船舶MMSI编号，9位数字
start_time	开始时间	int	是	Unix时间戳
end_time	结束时间	int	是	Unix时间戳，单次查询时间间隔不超过1周

请求示例

GET https://api.shipxy.com/apicall/v3/GetVShipImgs?key=您的API Key&mmsi=413904861&start_time=1751334377&end_time=1751939177

返回参数

参数名	名称	类型	说明
total	全部数量	int	返回图片的总数量
data	截图数据	array	截图列表
data[].image_url	截图查看地址	string	图片URL，可直接访问查看
data[].image_time	截图时间	string	北京时间，格式"2025-03-02 22:22:10"
data[].image_time_utc	截图时间	int	Unix时间戳
data[].lng	经度	double	WGS84坐标系，截图时船舶位置
data[].lat	纬度	double	WGS84坐标系，截图时船舶位置
data[].position	位置描述	string	截图时刻船舶所在位置描述
data[].mmsi	船舶MMSI	uint32	船舶MMSI编号
data[].ship_name	船舶名称	string	船舶名称
data[].device_name	设备名称	string	视频设备安装位置

返回示例

{
  "status": 0,
  "msg": "",
  "total": 1000,
  "data": [
    {
      "img_url": "https://hik.shipxy.com/cv/413904861/2025/07/01/2025-07-01_21_21_35_3070.jpg",
      "image_time": "2025-07-01 21:21:00",
      "image_time_utc": 1751376060,
      "lng": 113.527933,
      "lat": 23.014968,
      "position": "广州市番禺区",
      "mmsi": "413904861",
      "ship_name": "粤新会货8233",
      "device_name": "驾驶台"
    }
  ]
}

六、AI事件查询接口

6.1 查询船舶视频事件记录

查询摄像头AI识别到的异常事件记录，包括设备离线、摄像头遮挡、人员入侵、开关舱门、船舶搭靠、疑似偷盗等事件。

请求地址

服务地址	请求方式
`/apicall/v3/GetVShipAiEvents`	GET

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	uint32	是	船舶MMSI编号，9位数字
start_time	开始时间	int	是	Unix时间戳
end_time	结束时间	int	是	Unix时间戳，单次查询时间间隔建议不超过1个月

请求示例

GET https://api.shipxy.com/apicall/v3/GetVShipAiEvents?key=您的API Key&mmsi=413904861&start_time=1751334377&end_time=1751939177

返回参数

参数名	名称	类型	说明
total	全部数量	int	查询时间范围内事件总数
data	事件数据	array	事件列表
data[].ship_name	船舶名称	string	船舶名称
data[].mmsi	船舶MMSI	uint32	船舶MMSI编号
data[].device_name	设备名称	string	视频设备安装位置
data[].type_name	事件类型	string	事件类型名称
data[].event_time	事件时间	string	北京时间，格式"2025-03-02 22:22:10"
data[].event_time_utc	事件时间	int	Unix时间戳
data[].position	位置描述	string	事件发生时的位置描述
data[].beginNaviStat	航行状态	string	事件发生时船舶航行状态（靠泊/航行中）
data[].img_url	截图URL	string	事件发生时自动截图的图片地址
data[].duration	持续时间	int	事件持续时间（分钟），仅设备离线事件有值
data[].lng	经度	double	WGS84坐标系，事件发生时的经度
data[].lat	纬度	double	WGS84坐标系，事件发生时的纬度
data[].sog	船速	float	事件发生时船速（节）

事件类型说明

type_name值	说明
设备离线	摄像头设备网络断开
摄像头遮挡	摄像头被物体遮挡
人员入侵	监控区域出现人员
开关舱门	船舶舱门被打开或关闭
船舶搭靠	有其他船舶靠近搭靠
疑似偷盗	AI检测到可能的偷盗行为

返回示例

{
  "status": 0,
  "msg": "",
  "total": 114,
  "data": [
    {
      "ship_name": "粤新会货8233",
      "mmsi": "413904861",
      "device_name": "驾驶台",
      "type_name": "人员入侵",
      "event_time": "2025-07-01 23:00:00",
      "event_time_utc": 1751382000,
      "position": "广州市番禺区",
      "beginNaviStat": "靠泊",
      "img_url": "https://open.ys7.com/api/lapp/mq/downloadurl?...",
      "duration": "",
      "lng": 113.527951,
      "lat": 23.014948,
      "sog": 0
    }
  ]
}

七、历史视频下载接口

7.1 创建视频录制任务

创建历史视频的云录制任务，将指定时间段的视频录制为可下载的文件。

说明：仅支持14天以内的历史视频云录制，单次录制时间段不超过30分钟。

请求地址

服务地址	请求方式	备注
`/apicall/v3/AddPlaybackRecordTask`	POST	14天以内的数据支持历史视频云录制并下载

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
device_id	设备序列号	string	是	视频设备序列号
task_id	任务ID	string	是	用户自行创建的任务ID，不超过64位字符，同一用户下不可重复
start_time	开始时间	string	是	格式：yyyyMMddHHmmss，开始时间不得超过当前时间
end_time	结束时间	string	是	格式：yyyyMMddHHmmss，单次录制时间段不超过30分钟

请求示例

POST https://api.shipxy.com/apicall/v3/AddPlaybackRecordTask?key=您的API Key&device_id=FF8544139&task_id=1234567&start_time=20250403123059&end_time=20250403125959

返回参数

参数名	说明
status	状态码
msg	返回消息，可能值：提交成功 / 任务id重复 / 无服务权限
data	任务标识

返回示例

{
  "status": 0,
  "msg": "提交成功;400-设备[FF8544139]未搜索到本地录像",
  "data": "249722d0d3784f5bbc3f9f211decbb1d"
}

7.2 终止视频录制任务

终止进行中的视频录制任务。已经完成的任务不能终止。

注意：历史视频即便被终止也会产生流量，流量按照终止时刻已录制好的文件大小统计。

请求地址

服务地址	请求方式	备注
`/apicall/v3/SetPlaybackRecordTaskCancel`	POST	进行中的任务可终止，已完成的任务不能终止

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
task_id	任务ID	string	是	要终止的视频录制任务ID

返回说明

返回消息	说明
回放任务已终止	终止成功
回放任务已录制完成，无法终止	任务已完成
无效的任务id	任务ID不存在
无服务权限	权限不足

7.3 查询视频录制任务状态

查询录制任务的状态，成功后返回文件下载地址。

说明：创建录制任务后，通常10-15分钟左右录制完成。只有状态为"成功"时才返回下载地址。

请求地址

服务地址	请求方式	备注
`/apicall/v3/PlaybackRecordTaskQuery`	GET	查询任务状态和文件下载地址

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
task_id	任务ID	string	是	要查询的视频录制任务ID

返回参数

参数名	名称	类型	说明
task_id	任务ID	string	视频录制任务ID
task_state	任务状态	int	0=准备中，1=成功，2=终止，3=失败，4=排队中，5=进行中，6=暂停
expire_time	过期时间	string	文件过期时间，请在过期前下载
url	下载地址	string	文件下载地址（仅成功状态返回）

任务状态码说明

状态码	状态	说明
0	准备中	任务已创建，正在准备
1	成功	录制完成，可下载文件
2	终止	任务被手动终止
3	失败	录制失败（如网络原因）
4	排队中	正在排队等待录制
5	进行中	正在录制中
6	暂停	录制暂停

注意：单个文件多次下载也会耗费流量，请尽量不要重复下载。

八、事件订阅管理接口

8.1 添加订阅船舶

将船舶添加到事件推送订阅列表，订阅后该船舶发生视频事件时将收到推送。

说明：订阅时会验证船舶是否在用户视频平台清单中，不在清单中的船舶将添加失败。

请求地址

服务地址	请求方式
`/apicall/v3/VShipSubscribeSet`	POST

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	string	是	要订阅的船舶MMSI编号
cell	手机号	string	否	绑定手机号，开通电话通知后事件发生时将拨打此号码

返回说明

返回消息	说明
添加视频监控船舶成功	添加成功
不具备权限	API Key权限不足
订阅船舶数量超限	已达到订阅数量上限
船舶不在用户的视频平台清单中	该船舶未关联到当前账号

手机号更新说明：多个设备可以使用同一个手机号码，如需变更手机号，可重新调用此接口传入新的cell值。

8.2 删除订阅船舶

将船舶从事件推送订阅列表中移除。

请求地址

服务地址	请求方式
`/apicall/v3/VShipSubscribeDel`	POST

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码
mmsi	船舶编号	string	是	要删除的船舶MMSI编号

返回说明

返回消息	说明
删除成功	删除成功
不具备权限	API Key权限不足
船舶不在订阅列表中	该船舶当前未被订阅

8.3 查询订阅船舶列表

查询当前账号下所有已订阅事件推送的船舶列表。

请求地址

服务地址	请求方式
`/apicall/v3/VShipSubscribeQuery`	POST

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码

返回参数

参数名	名称	类型	说明
total	列表总数	int	订阅船舶总数
data	船舶信息	array	订阅船舶列表
data[].mmsi	船舶MMSI	uint32	船舶MMSI编号
data[].cell	手机号	string	绑定的手机号码

九、流量查询接口

9.1 查询历史视频下载流量

查询历史视频下载的流量包使用情况。

请求地址

服务地址	请求方式
`/apicall/v3/GetPlaybackDetail`	GET

请求参数

参数名	名称	类型	必填	说明
key	授权码	string	是	船讯网授权码

返回参数

参数名	名称	类型	说明
flow_total	总流量包	double	总的历史视频下载流量包数量，单位：分钟
flow_used	已使用流量	double	已使用的流量包数量，单位：分钟
flow_remaining	剩余流量	double	剩余的流量包数量，单位：分钟

返回示例

{
  "status": 0,
  "msg": "",
  "data": {
    "flow_total": 100,
    "flow_used": 1.97,
    "flow_remaining": 98.03
  }
}

十、推送数据格式说明

当订阅的船舶发生视频事件时，系统会实时推送事件数据。以下是推送数据的格式说明。

10.1 推送方式

事件通过HTTP POST方式推送至客户预先配置的接收地址（Webhook）。

10.2 推送数据结构

参数名	名称	类型	说明
ship_name	船舶名称	string	船舶名称
mmsi	船舶MMSI	uint32	船舶MMSI编号，9位数字
device_name	设备名称	string	视频设备安装位置，如"驾驶台"、"左舷"等
type_name	事件类型	string	事件类型名称
description	事件描述	string	疑似偷盗子类型描述（仅疑似偷盗事件有值）
event_time	事件时间	string	北京时间，格式"2025-03-02 22:22:10"
event_time_utc	事件时间	int	Unix时间戳
lat	纬度	double	WGS84坐标系，事件发生时的纬度
lng	经度	double	WGS84坐标系，事件发生时的经度
position	位置描述	string	事件发生位置描述
beginNaviStat	航行状态	string	事件发生时的航行状态（靠泊/到锚/在航）
img_url	截图地址	string	事件发生时自动截图的URL
sog	船速	float	事件发生时的船速（节）

10.3 疑似偷盗事件描述值

description值	说明
携带装载容器	检测到人员携带装载容器
携带推铲工具	检测到人员携带推铲类工具
管线设备接触	检测到管线设备被异常接触
小船搭靠	检测到小型船只靠近搭靠

注意：只有开通疑似偷盗事件监控权限，并且触发疑似偷盗事件时，description字段才会有返回。

10.4 推送示例

{
  "ship_name": "粤新会货8233",
  "mmsi": 413904861,
  "device_name": "驾驶台",
  "type_name": "疑似偷盗",
  "description": "携带装载容器",
  "event_time": "2025-07-01 23:00:00",
  "event_time_utc": 1751382000,
  "lat": 23.014948,
  "lng": 113.527951,
  "position": "广州市番禺区",
  "beginNaviStat": "靠泊",
  "img_url": "https://open.ys7.com/api/lapp/mq/downloadurl?...",
  "sog": 0
}

十一、状态码说明

11.1 通用状态码

状态码	说明
0	请求成功
14	来源域错误 - API Key绑定了特定域名，请使用正确的来源域名
15	无接口权限 - 该接口需要开通权限，请联系商务
16	请求参数错误 - 检查输入参数格式，如MMSI是否为9位数字
17	请求频率超限 - 降低请求频率，或升级套餐
18	无此船数据 - 该船舶暂无数据，请确认输入是否正确
19	查询时间段过长 - 缩短查询时间范围
20	账户已过期 - 请联系商务续费

11.2 视频监控服务特有状态码

状态码/消息	说明
船舶未绑定摄像头	该船舶尚未绑定视频设备
设备离线	摄像头设备当前处于离线状态
订阅船舶数量超限	已达到最大订阅船舶数量限制
船舶不在用户的视频平台清单中	该船舶未与当前账号关联
任务id重复	同一用户下任务ID不能重复
无效的任务id	指定的任务ID不存在

文档结束
场景化的应用示例请参考《船讯网视频监控场景应用指南》
如有疑问，请联系船讯网技术支持团队：service@shipxy.com | 400-010-8558

视频监控API服务说明

船讯网视频监控API服务说明#

目录#

一、接口规范说明#

1.1 通信协议#

1.2 服务基地址#

1.3 认证方式#

1.4 通用返回结构#

1.5 通用请求头#

二、设备状态查询接口#

2.1 查询船舶视频设备状态#

请求地址#

请求参数#

请求示例#

返回参数#

返回示例#

三、实时视频查看接口#

3.1 获取船舶实时视频#

请求地址#

请求参数#

请求示例#

返回参数#

返回示例#

四、历史视频查看接口#

4.1 获取船舶历史视频#

请求地址#

请求参数#

请求示例#

返回参数#

返回示例#

五、定时截图查询接口#

5.1 查询船舶定时截图#

请求地址#

请求参数#

请求示例#

返回参数#

返回示例#

六、AI事件查询接口#

6.1 查询船舶视频事件记录#

请求地址#

请求参数#

请求示例#

返回参数#

事件类型说明#

返回示例#

七、历史视频下载接口#

7.1 创建视频录制任务#

请求地址#

请求参数#

请求示例#

返回参数#

返回示例#

7.2 终止视频录制任务#

请求地址#

请求参数#

返回说明#

7.3 查询视频录制任务状态#

请求地址#

请求参数#

返回参数#

任务状态码说明#

八、事件订阅管理接口#

8.1 添加订阅船舶#

请求地址#

请求参数#

返回说明#

8.2 删除订阅船舶#

请求地址#

请求参数#

返回说明#

8.3 查询订阅船舶列表#

请求地址#

请求参数#

返回参数#

九、流量查询接口#

9.1 查询历史视频下载流量#

请求地址#

请求参数#

返回参数#

返回示例#

船讯网视频监控API服务说明

目录

一、接口规范说明

1.1 通信协议

1.2 服务基地址

1.3 认证方式

1.4 通用返回结构

1.5 通用请求头

二、设备状态查询接口

2.1 查询船舶视频设备状态

请求地址

请求参数

请求示例

返回参数

返回示例

三、实时视频查看接口

3.1 获取船舶实时视频

请求地址

请求参数

请求示例

返回参数

返回示例

四、历史视频查看接口

4.1 获取船舶历史视频

请求地址

请求参数

请求示例

返回参数

返回示例

五、定时截图查询接口

5.1 查询船舶定时截图

请求地址

请求参数

请求示例

返回参数

返回示例

六、AI事件查询接口

6.1 查询船舶视频事件记录

请求地址

请求参数

请求示例

返回参数

事件类型说明

返回示例

七、历史视频下载接口

7.1 创建视频录制任务

请求地址

请求参数

请求示例

返回参数

返回示例

7.2 终止视频录制任务

请求地址

请求参数

返回说明

7.3 查询视频录制任务状态

请求地址

请求参数

返回参数

任务状态码说明

八、事件订阅管理接口

8.1 添加订阅船舶

请求地址

请求参数

返回说明

8.2 删除订阅船舶

请求地址

请求参数

返回说明

8.3 查询订阅船舶列表

请求地址

请求参数

返回参数

九、流量查询接口

9.1 查询历史视频下载流量

请求地址

请求参数

返回参数

返回示例

十、推送数据格式说明