视频设备控制接口

一、应用场景

视频设备控制服务是物联网平台提供的用于客户对视频设备的控制功能。开发者可以使用视频设备控制相关接口，获取视频设备直播流地址，录像回放地址，手动抓拍图片URL以及摄像机云台控制等功能。开发者此类接口可实现如下业务场景：

  1. 开发者获取设备直播流地址、录像回放地址，在网页或者APP上进行视频播放及录像回播；

  2. 通过抓拍后的图片进行图像识别、视频分析等；

  3. 网页或APP通过云台控制功能实时控制摄像头方向和角度；

二、功能说明

客户在物联网平台管理台【设备中心】配置后，可以在物联网平台管理台的设备中心中接入视频设备。从而通过调用以下文档提供的API接口，来实现使用对视频设备的拉流播放、录像回放、抓拍图片、云台控制等功能。

设备控制功能主要包含以下几种：

拉流播放
录像回放
抓拍图片
云台控制

物联网平台提供多种视频拉流格式供客户选择使用，分别是https-flv格式流地址、rtmp格式流地址、https-hls格式流地址；

下面分别描述三种流参考建议：

属性 RTMP格式 Https-HLS格式 Https-FLV格式
协议 TCP长连接 HTTPS短连接 HTTPS长连接
原理 每个时刻的数据收到后立刻转发 集合一段时间的数据，生成TS切片文件（三片），并更新m3u8索引 同RPMP，使用HTTP协议（80端口）
延时 1-3秒 5-20秒（依切片情况） 1-3秒
WEB支持 H5中需要使用插件 支持H5 支持H5
其他 跨平台支持较差，需要Flash技术支持 播放时需要多次请求，对于网络质量要求高 不需要Flash技术支持，不支持多音频流、多视频流、不便于SEEK（即拖进度条）
流地址示例 rtmp://rtmp-play.xlink.cn/pv_demo/A44C3B81D14608_1 https://hls-play.xlink.cn/pv_demo/A44C3B81D14608_1.m3u8 https://flv-play.xlink.cn/pv_demo/A44C3B81D14608_1.flv

三、前提条件

  1. 参考管理台设备部署手册《视频设备部署操作手册》，确保在管理台【设备中心】中完成对设备的接入上线；

  2. 设备已经配置到项目上。

  3. 如果是阿里IOT来源的设备，需要配置对应的appKey与appSecret。详情请看

四、关键流程图

无

五、API列表

5.1. 实时视频

接口描述

根据设备、项目与产品信息获取视频流地址

（1）设备来源于阿里IOT平台，则使用LinkVersion获取视频流地址。（需要在物联云平台管理台–>项目管理–>项目列表–>项目详情–>编辑项目，添加自定义字段appKey与appSecret，两个值对应阿里IOT平台项目上的appKey与appSecret）

（2）设备来源非阿里IOT平台，则使用物联云平台自研驱动获取视频设备直播流地址。

请求方式

POST

请求地址

/v3/business/middle/device/startstream

请求头

名称 必填 类型 备注
Access-Token true String 企业权限/外部权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
deviceId body true Integer 设备id
productValue body true Object
productValue.productId body true String 产品id
project body true Object
project.projectId body true String 项目id

请求示例：

{ 
	"deviceId": 12345, 
	"productValue":{
        productId:"xxxx"
    },
    "project":{
        projectId:"xxxxxxxxxxx"
    }
}

返回参数说明

名称 必填 类型 备注
responseTime True Date 响应时间
code True String 成功、错误码
msg True String 对于返回值的详细说明
data False Object
data.video_flv_url False String flv格式流地址
data.video_rtmp_url False String rtmp格式流地址
data.video_rtsp_url False String rtsp格式流地址
data.video_url False String 默认流地址
data.video_ws_url False String ws格式流地址
data.video_hls_url False String hls格式流地址
data.online_state False Integer 设备在线状态
data.model False String 模型值(阿里：videoLinkVersionDomainModel, 物模型：videoTmlDomainModel)，返回videoLinkVersionDomainModel则视频流来自阿里LinkVersion。videoTmlDomainModel则来自与物联云平台自研视频驱动。

返回示例：

{
    "responseTime":"2021-11-17T08:11:18.095+0000",
    "code":"000000",
    "status":"200",
    "msg":"请求成功",
    "data":{
        "model":"videoTmlDomainModel",
        "online_state":1,
        "video_flv_url":"xxxxx",
        "video_url":"xxxxx",
        "video_ws_url":"xxxxx",
        "video_hls_url":"xxxxx",
        "video_rtsp_url":"xxxx",
        "video_rtmp_url":"xxxxx"
    }
}

错误码：

错误码 描述
000000 请求成功
5031001 服务端发生异常
4002001 第三方接口调用失败
4001005 参数不能为空

5.2. 录像回放

接口描述

根据设备、项目与产品信息获取视频设备录像播放流地址

（1）设备来源于阿里IOT平台，则使用LinkVersion获取录像流地址。（需要在物联云平台管理台–>项目管理–>项目列表–>项目详情–>编辑项目，添加自定义字段appKey与appSecret，两个值对应阿里IOT平台项目上的appKey与appSecret）

（2）设备来源非阿里IOT平台，则使用物联云平台自研驱动获取视频设备录像流地址。

请求方式

POST

请求地址

/v3/business/middle/device/playBack

请求头

名称 必填 类型 备注
Access-Token true String 企业权限/外部权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
deviceId body true Integer 设备id
productValue body true Object
productValue.productId body true String 产品id
project body true Object
project.projectId body true String 项目id
opt body true JSONObject 操作指令
opt.order body false Integer 默认 0 playback_start（开始录像放）

操作类型：

@0 playback_start（开始录像回放）

@1 playback_control (录像控制)

@2 playback_stop (停止录像回放) |
| opt.input | body | true | JSONObject | 根据操作类型具体而定见附录A |

请求示例：

{
    "deviceId": 12345,
    "productValue": {
        "productId": "xxx"
    },
    "project": {
        "projectId": "xxxx"
    },
    "opt": {
        "order": 0,
        "input": {
            "start_time": "2021-11-16T00:00:00",
            "end_time": "2021-11-17T01:00:00"
        }
    }
}

返回参数说明

名称 必填 类型 备注
responseTime True Date 响应时间
code True String 成功、错误码
msg True String 对于返回值的详细说明
data False Object
data.video_flv_url False String flv格式流地址
data.video_rtmp_url False String rtmp格式流地址
data.video_rtsp_url False String rtsp格式流地址
data.video_url False String 默认流地址
data.video_ws_url False String ws格式流地址
data.video_hls_url False String hls格式流地址
data.callId False String 用于回放控制的callId（物联云平台设备可用）
data.model False String 模型值(阿里：videoLinkVersionDomainModel, 物模型：videoTmlDomainModel)

返回示例：

{
    "responseTime":"2021-11-17T08:10:12.743+0000",
    "code":"000000",
    "status":"200",
    "msg":"请求成功",
    "data":{
        "model":"videoTmlDomainModel",
        "video_rtsp_url":"xxxx",
        "video_rtmp_url":"xxx",
        "callId":"xxxx",
        "video_flv_url":"xxxxxx",
        "video_url":"xxxx",
        "video_ws_url":"",
        "video_hls_url":"xxxxx"
    }
}

错误码：

错误码 描述
000000 请求成功
5031001 服务端发生异常
4002001 第三方接口调用失败
4001005 参数不能为空

5.3. 手动抓图

接口描述

视频设备手动抓图，获取图片地址。

（1）设备来源于阿里IOT平台，则使用LinkVersion抓拍图片。（需要在物联云平台管理台–>项目管理–>项目列表–>项目详情–>编辑项目，添加自定义字段appKey与appSecret，两个值对应阿里IOT平台项目上的appKey与appSecret）

（2）设备来源非阿里IOT平台，则使用物联云平台自研驱动获取抓拍的图片。

请求方式

POST

请求地址

/v3/business/middle/device/snapshots

请求头

名称 必填 类型 备注
Access-Token true String 企业权限/外部权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
deviceId body true Integer 设备id
productValue body true Object
productValue.productId body true String 产品id
project body true Object
project.projectId body true String 项目id

请求示例：

{ 
	"deviceId": 12345, 
	"productValue":{
        productId:"xxxx"
    },
    "project":{
        projectId:"xxxxxxxxxxx"
    }
}

返回参数说明

名称 必填 类型 备注
responseTime True Date 响应时间
code True String 成功、错误码
msg True String 对于返回值的详细说明
data False Object
data.private_url False String 私有资源地址，局域网上使用。
data.public_url False String 公有资源地址，公网上使用。
data.key False 获取异步抓图结果的key(第三方设备模型使用)
data.model False String 模型值(阿里：videoLinkVersionDomainModel, 物模型：videoTmlDomainModel)

返回示例：

{
    "responseTime":"2021-11-17T08:17:26.669+0000",
    "code":"000000",
    "status":"200",
    "msg":"请求成功",
    "data":{
        "model":"videoTmlDomainModel",
        "private_url":"xxxx",
        "public_url":"xxx",
        "key":"xxxx"
    }
}

错误码：

错误码 描述
000000 请求成功
5031001 服务端发生异常
4002001 第三方接口调用失败
4001005 参数不能为空

5.4. 云台控制

接口描述

视频设备云台控制。

（2）使用物联云平台自研驱动进行设备云台控制。

请求方式

POST

请求地址

/v3/business/middle/device/ptz

请求头

名称 必填 类型 备注
Access-Token true String 企业权限/外部权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
deviceId body true Integer 设备id
productValue body true Object
productValue.productId body true String 产品id
project body true Object
project.projectId body true String 项目id
opt body true Object 操作指令
opt.order body false Integer 默认 0 ptz_start（开始云台控制）

操作类型：

@0 ptz_start（开始云台控制）

@1 ptz_stop （停止云台控制） |
| opt.input | body | true | Object | 根据操作类型具体而定见附录A |

请求示例：

{
    "deviceId":113,
    "productValue":{
        "productId":"xxx"
    },
    "project":{
        "projectId":"xxx"
    },
    "opt":{
        "order":0,
        "input":{
            "ptz_command":6,
            "ptz_speed":1
        }
    }
}

返回参数说明

名称 必填 类型 备注
responseTime True Date 响应时间
code True String 成功、错误码
msg True String 对于返回值的详细说明
data False Object
data.id False String 指令主键ID
data.model False String 模型值(阿里：videoLinkVersionDomainModel, 物模型：videoTmlDomainModel)

返回示例：

{
    "responseTime":"2021-11-17T08:26:31.267+0000",
    "code":"000000",
    "status":"200",
    "msg":"请求成功",
    "data":{
        "model":"videoTmlDomainModel",
        "id":"xxx"
    }
}

错误码：

错误码 描述
000000 请求成功
5031001 服务端发生异常
4002001 第三方接口调用失败
4001005 参数不能为空

六、附录

附录A

关于设备操作参数中的input说明

1、回放(playBack)

1.1、playback_start

名称 必填 类型 备注
input true object
input.start_time true Date 回放开始时间
input.end_time true Date 回放结束时间

示例

{
    "input": {
        "start_time": "yyyy-MM-dd'T'HH:mm:ss",
        "end_time": "yyyy-MM-dd'T'HH:mm:ss"
    }
}

1.2、回放控制（playback_control）

名称 必填 类型 备注
input true object
input.callId true String 用于回放控制的callId
input.command true Integer 历史回放控制@ 1 正常播放；@ 2 暂停；@ 3 倍数播放；@ 4 停止回放；@ 5 回放保活；@ 6 查询当前播放到什么位置（返回秒数） ps：当选择3倍速播放时： scale Number(float) 控制播放倍速（快进，快退的速度） 1 = 正常播放， 大于0小于1为慢放，大于1为快放，负数为倒放（仅command = 3 时可用）当选择1的时候可以进行历史录像跳转： * range Number(int32) : 播放位置跳转偏移量：从当前位置跳转到指定的range（单位： s）的时间点播放（仅 command = 1 时可用）
input.scale false float 回放倍数（当commad = 3时可用）@ 0.5（慢放）；@ 1（正常播放）；@ 2 （快速播放）；@ 2.5 （快速播放）；@ 3（快速播放）；@ 4（快速播放）。
input.range false int 偏移量（当commad = 1时可用）

示例

{
    "input": {
        "callId": "xxxx",
        "command": 1
    }
}

1.2、回放停止（playback_stop）

PS：推荐使用回放控制中的停止回放指令

名称 必填 类型 备注
input true object
input.callId false String

示例

{
    "input": {
        "callId": "xxxx"
    }
}

2、云台控制（ptz）

2.1、开始云台控制（ptz_start）

名称 必填 类型 备注
input true object
input.ptz_command true Integer 云台控制枚举@ 1 向上移动（up）；@ 2 向下移动（down）；@ 3 向左移动（left）；@ 4 向右移动（right）；@ 5 左上（up_left）；@ 6 右上（up_right）；@ 7 左下（down_left）；@ 8 右下（down_right）；@ 9 镜头变焦全景图像（zoom_out）；@ 10 镜头变焦特写图像（zoom_in）；@ 11 调整镜头聚焦远（focus_far）；@ 12 调整镜头聚焦进（focus_near）；@ 13 镜头光圈大（aperture_open）；@ 14 镜头光圈小（aperture_close）。
input.ptz_speed false Integer 速度

示例

{
    "input": {
        "ptz_command": 1,
        "ptz_speed": 1
    }
}
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题