向云端推送图片

VSaaS 设备端图片推送相关 API 文档 | TUTK SDK 开发手册

一、概述

本文档将描述VSaaS设备端图片推送相关核心功能，包括vsaasInfo.txt文件说明、获取推图地址、推图片到云端三个关键环节。设备端需先通过APP获取vsaasInfo配置信息，再依次完成推图地址获取、图片上传流程，最终实现图片数据的云端存储。

前置条件：设备端需从第三方APP获取有效的vsaasInfo配置（含stoken、UDID等核心信息），用于接口身份校验。

二、vsaasInfo.txt 说明

vsaasInfo.txt是设备端保存VSaaS服务器相关配置信息的文件，由APP通过AVAPI发送给设备端，设备端SDK接收后通过回调返回给应用层保存，用于后续图片推送相关接口调用。

文件结构示例

{ "args": { "url": "https://cn-vsaasapi-tutk.kalay.net.cn/vsaas/api/v1/stream/stream_url/TUTKOITUVOAXGUWJFWJTEDKA9T3WP7348G6GUH71?stoken=S9s41Xlz-tCYrHpCJdh_4pwUy7bKqrmj9g-Ga7feNpSN3PTFDkTMITw274wsnmOu_1uhfvljy-dFjTLE2tUTQdOYizlFq2BzwZ95ekVR_IbgPnpkKwaHC78lPLzAMc0ASkfV16BQjqMF8wu_-rsk9g==", "header": { "Authentication": "Bearer cumweamhl18l7w7kmdr9", "User-Agent": "TUTK Device" } }, "func": "setCloudRecordingEndpoint" }

字段说明

字段路径	类型	说明
args.url	String	VSaaS后端服务器基础地址，包含设备UDID和stoken，用于推导后续接口URL
args.header	Object	HTTP请求头信息，用于图片推送接口的身份验证
args.header.Authentication	String	授权头信息，格式为"Bearer {token}"
args.header.User-Agent	String	客户端标识，固定为"TUTK Device"
func	String	功能名称，固定为"setCloudRecordingEndpoint"

核心用途：从args.url中提取设备UDID和stoken，作为后续「获取推图地址」接口的必填参数。

三、API接口

（一）获取推图地址

设备端通过此接口获取图片推送的云端地址，用于后续图片上传操作，推图前需优先调用此接口。

1. 请求说明

项	说明
HTTP请求方式	GET
请求URL	https://host:port/vsaas/api/v1/stream/stream_url/{UDID}?protocol={protocol}&stoken={stoken}&event_id={event_id}&starttime={timestamp}&media_type={media_type}
请求头（Header）	参考vsaasInfo.txt中的args.header配置（含Authentication、User-Agent）

2. 请求参数

参数名	类型	必选	说明
UDID	String	是	设备唯一标识，从vsaasInfo.txt的args.url中提取
stoken	String	是	推图专用Token，从vsaasInfo.txt的args.url中提取
event_id	String	是	事件ID，标识当前上传图片对应的事件类型
protocol	String	是	固定值："upload"（标识为上传操作）
starttime	String	是	事件触发时间戳（秒级），需与推图时图片命名的毫秒级时间戳为1000倍关系
media_type	String	是	固定值："2"（标识媒体类型为图片）

3. 响应说明

3.1 响应参数

参数名	类型	说明
code	Int	错误码：1=成功
message	String	错误信息（成功时为空）
result	Object	响应核心数据
result.contract_type	String	存储类型："event"（事件存储）
result.disable_thumbnail	Boolean	是否禁用缩略图：false=启用，true=禁用
result.event_duration	Int	事件时长（秒）
result.event_recording_max_length	Int	事件存储最大长度（秒）
result.max_storage_size	Int	最大存储容量（单位：GB）
result.media_type	Int	媒体类型标识（默认255）
result.recording_max_kbps	Int	最大上传码率（kbps）
result.url	String	推图地址（含OTP临时授权码），用于后续图片上传
result.video_max_fps	Int	最大帧率（fps）
result.video_max_height	Int	图片最大高度（像素）
result.video_max_width	Int	图片最大宽度（像素）
result.vsaas_type	String	云服务类型（如"aws"）

3.2 响应状态码

状态码	徽章	说明
200	成功	请求成功，返回推图地址及配置信息
400	参数错误	必填参数缺失或格式错误

4. 接口示例

请求示例（curl）

curl "https://cn-vsaasapi-tutk.kalay.net.cn/vsaas/api/v1/stream/stream_url/TUTKOITUVOAXGUWJFWJTEDKA9T3WP7348G6GUH71?stoken=S9s41Xlz-tCYrHpCJdh_4pwUy7bKqrmj9g-Ga7feNpSN3PTFDkTMITw274wsnmOu_1uhfvljy-dFjTLE2tUTQdOYizlFq2BzwZ95ekVR_IbgPnpkKwaHC78lPLzAMc0ASkfV16BQjqMF8wu_-rsk9g==&protocol=upload&event_id=999&starttime=1720082145&media_type=2"

响应示例（成功）

{ "code": 1, "message": "", "result": { "contract_type": "event", "disable_thumbnail": false, "event_duration": 7, "event_recording_max_length": 30, "max_storage_size": 100, "media_type": 255, "recording_max_kbps": 1024, "url": "https://cn-vpstream01-tutk.kalay.net.cn:8080/post_stream/v1/TUTKOITUVOAXGUWJFWJTEDKA9T3WP7348G6GUH71?OTP=5E44DCADE2112F836610&event_id=999&starttime=1720082145&stoken=S9s41Xlz-tCYrHpCJdh_4pwUy7bKqrmj9g-Ga7feNpSN3PTFDkTMITw274wsnmOu_1uhfvljy-dFjTLE2tUTQdOYizlFq2BzwZ95ekVR_IbgPnpkKwaHC78lPLzAMc0ASkfV16BQjqMF8wu_-rsk9g%3D%3D", "video_max_fps": 25, "video_max_height": 200, "video_max_width": 200, "vsaas_type": "aws" } }

（二）推图片到云端

设备端使用「获取推图地址」接口返回的推图地址，以multipart/form-data格式将图片文件上传至VSaaS云端，仅支持JPG格式图片。

1. 请求说明

项	说明
HTTP请求方式	POST
请求URL	从「获取推图地址」接口返回的result.url（含OTP临时授权码及核心参数）
请求头（Header）	Content-Type: multipart/form-data; 参考vsaasInfo.txt中的args.header配置（含Authentication、User-Agent）

2. 请求参数

参数类型	参数名	类型	必选	说明
URL参数（已包含在推图地址中）	OTP	String	是	临时授权码，每次推图唯一
	stoken	String	是	推图专用Token，与「获取推图地址」时一致
	event_id	String	是	事件ID，与「获取推图地址」时一致
	starttime	String	是	事件触发时间戳（秒级），与「获取推图地址」时一致
	UDID	String	是	设备唯一标识，与「获取推图地址」时一致
URL可选参数	tags	String	否	事件标签，多个标签用逗号分隔（如"门口,异常"）
Form-Data参数（media_file）	filename	String	是	命名规则：{毫秒级时间戳}_D0E.jpg（例：1720082145000_D0E.jpg）；毫秒级时间戳需为starttime*1000
	Content-Type	String	是	固定值：image/jpg（仅支持JPG格式图片）
	文件内容	Binary	是	JPG图片二进制数据

3. 响应状态码

状态码	徽章	说明
200	成功	图片上传成功
400	参数错误	Form-Data参数缺失、filename格式错误或图片格式非法
403	授权失败	OTP过期、stoken无效或推图地址失效

4. 接口示例

请求示例（curl）

curl -XPOST \ -H "Content-Type: multipart/form-data" \ -H "Authentication: Bearer cumweamhl18l7w7kmdr9" \ -H "User-Agent: TUTK Device" \ -F 'media_file=@1720082145000_D0E.jpg;type=image/jpg' \ 'https://cn-vpstream01-tutk.kalay.net.cn:8080/post_stream/v1/TUTKOITUVOAXGUWJFWJTEDKA9T3WP7348G6GUH71?OTP=5E44DCADE2112F836610&event_id=999&starttime=1720082145&stoken=S9s41Xlz-tCYrHpCJdh_4pwUy7bKqrmj9g-Ga7feNpSN3PTFDkTMITw274wsnmOu_1uhfvljy-dFjTLE2tUTQdOYizlFq2BzwZ95ekVR_IbgPnpkKwaHC78lPLzAMc0ASkfV16BQjqMF8wu_-rsk9g%3D%3D'