首頁(yè) > 文檔中心 > 云端服務(wù) > 云端存儲(chǔ) > 設(shè)備端接入

向云端推送圖片

VSaaS 設(shè)備端圖片推送相關(guān) API 文檔 | TUTK SDK 開(kāi)發(fā)手冊(cè)

一、概述

本文檔將描述VSaaS設(shè)備端圖片推送相關(guān)核心功能，包括vsaasInfo.txt文件說(shuō)明、獲取推圖地址、推圖片到云端三個(gè)關(guān)鍵環(huán)節(jié)。設(shè)備端需先通過(guò)APP獲取vsaasInfo配置信息，再依次完成推圖地址獲取、圖片上傳流程，最終實(shí)現(xiàn)圖片數(shù)據(jù)的云端存儲(chǔ)。

前置條件：設(shè)備端需從第三方APP獲取有效的vsaasInfo配置（含stoken、UDID等核心信息），用于接口身份校驗(yàn)。

二、vsaasInfo.txt 說(shuō)明

vsaasInfo.txt是設(shè)備端保存VSaaS服務(wù)器相關(guān)配置信息的文件，由APP通過(guò)avSendIOCtrl發(fā)送給設(shè)備端，設(shè)備端SDK接收后通過(guò)回調(diào)返回給應(yīng)用層保存，用于后續(xù)圖片推送相關(guān)接口調(diào)用。

文件結(jié)構(gòu)示例

{ "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" }

字段說(shuō)明

字段路徑	類(lèi)型	說(shuō)明
args.url	String	VSaaS后端服務(wù)器基礎(chǔ)地址，包含設(shè)備UDID和stoken，用于推導(dǎo)后續(xù)接口URL
args.header	Object	HTTP請(qǐng)求頭信息，用于圖片推送接口的身份驗(yàn)證
args.header.Authentication	String	授權(quán)頭信息，格式為"Bearer {token}"
args.header.User-Agent	String	客戶端標(biāo)識(shí)，固定為"TUTK Device"
func	String	功能名稱(chēng)，固定為"setCloudRecordingEndpoint"

核心用途：從args.url中提取設(shè)備UDID和stoken，作為后續(xù)「獲取推圖地址」接口的必填參數(shù)。

三、API接口

（一）獲取推圖地址

設(shè)備端通過(guò)此接口獲取圖片推送的云端地址，用于后續(xù)圖片上傳操作，推圖前需優(yōu)先調(diào)用此接口。

1. 請(qǐng)求說(shuō)明

項(xiàng)	說(shuō)明
HTTP請(qǐng)求方式	GET
請(qǐng)求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}
請(qǐng)求頭（Header）	參考vsaasInfo.txt中的args.header配置（含Authentication、User-Agent）

2. 請(qǐng)求參數(shù)

參數(shù)名	類(lèi)型	必選	說(shuō)明
UDID	String	是	設(shè)備唯一標(biāo)識(shí)，從vsaasInfo.txt的args.url中提取
stoken	String	是	推圖專(zhuān)用Token，從vsaasInfo.txt的args.url中提取
event_id	String	是	事件ID，標(biāo)識(shí)當(dāng)前上傳圖片對(duì)應(yīng)的事件類(lèi)型
protocol	String	是	固定值："upload"（標(biāo)識(shí)為上傳操作）
starttime	String	是	事件觸發(fā)時(shí)間戳（秒級(jí)），需與推圖時(shí)圖片命名的毫秒級(jí)時(shí)間戳為1000倍關(guān)系
media_type	String	是	固定值："2"（標(biāo)識(shí)媒體類(lèi)型為圖片）

3. 響應(yīng)說(shuō)明

3.1 響應(yīng)參數(shù)

參數(shù)名	類(lèi)型	說(shuō)明
code	Int	錯(cuò)誤碼：1=成功
message	String	錯(cuò)誤信息（成功時(shí)為空）
result	Object	響應(yīng)核心數(shù)據(jù)
result.contract_type	String	存儲(chǔ)類(lèi)型："event"（事件存儲(chǔ)）
result.disable_thumbnail	Boolean	是否禁用縮略圖：false=啟用，true=禁用
result.event_duration	Int	事件時(shí)長(zhǎng)（秒）
result.event_recording_max_length	Int	事件存儲(chǔ)最大長(zhǎng)度（秒）
result.max_storage_size	Int	最大存儲(chǔ)容量（單位：GB）
result.media_type	Int	媒體類(lèi)型標(biāo)識(shí)（默認(rèn)255）
result.recording_max_kbps	Int	最大上傳碼率（kbps）
result.url	String	推圖地址（含OTP臨時(shí)授權(quán)碼），用于后續(xù)圖片上傳
result.video_max_fps	Int	最大幀率（fps）
result.video_max_height	Int	圖片最大高度（像素）
result.video_max_width	Int	圖片最大寬度（像素）
result.vsaas_type	String	云服務(wù)類(lèi)型（如"aws"）

3.2 響應(yīng)狀態(tài)碼

狀態(tài)碼	徽章	說(shuō)明
200	成功	請(qǐng)求成功，返回推圖地址及配置信息
400	參數(shù)錯(cuò)誤	必填參數(shù)缺失或格式錯(cuò)誤

4. 接口示例

請(qǐng)求示例（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"

響應(yīng)示例（成功）

{ "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" } }

（二）推圖片到云端

設(shè)備端使用「獲取推圖地址」接口返回的推圖地址，以multipart/form-data格式將圖片文件上傳至VSaaS云端，僅支持JPG格式圖片。

1. 請(qǐng)求說(shuō)明

項(xiàng)	說(shuō)明
HTTP請(qǐng)求方式	POST
請(qǐng)求URL	從「獲取推圖地址」接口返回的result.url（含OTP臨時(shí)授權(quán)碼及核心參數(shù)）
請(qǐng)求頭（Header）	Content-Type: multipart/form-data; 參考vsaasInfo.txt中的args.header配置（含Authentication、User-Agent）

2. 請(qǐng)求參數(shù)

參數(shù)類(lèi)型	參數(shù)名	類(lèi)型	必選	說(shuō)明
URL參數(shù)（已包含在推圖地址中）	OTP	String	是	臨時(shí)授權(quán)碼，每次推圖唯一
	stoken	String	是	推圖專(zhuān)用Token，與「獲取推圖地址」時(shí)一致
	event_id	String	是	事件ID，與「獲取推圖地址」時(shí)一致
	starttime	String	是	事件觸發(fā)時(shí)間戳（秒級(jí)），與「獲取推圖地址」時(shí)一致
	UDID	String	是	設(shè)備唯一標(biāo)識(shí)，與「獲取推圖地址」時(shí)一致
URL可選參數(shù)	tags	String	否	事件標(biāo)簽，多個(gè)標(biāo)簽用逗號(hào)分隔（如"門(mén)口,異常"）
Form-Data參數(shù)（media_file）	filename	String	是	命名規(guī)則：{毫秒級(jí)時(shí)間戳}_D0E.jpg（例：1720082145000_D0E.jpg）；毫秒級(jí)時(shí)間戳需為starttime*1000
	Content-Type	String	是	固定值：image/jpg（僅支持JPG格式圖片）
	文件內(nèi)容	Binary	是	JPG圖片二進(jìn)制數(shù)據(jù)

3. 響應(yīng)狀態(tài)碼

狀態(tài)碼	徽章	說(shuō)明
200	成功	圖片上傳成功
400	參數(shù)錯(cuò)誤	Form-Data參數(shù)缺失、filename格式錯(cuò)誤或圖片格式非法
403	授權(quán)失敗	OTP過(guò)期、stoken無(wú)效或推圖地址失效

4. 接口示例

請(qǐng)求示例（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'

向云端推送圖片

一、概述

二、vsaasInfo.txt 說(shuō)明

三、API接口

一、概述

二、vsaasInfo.txt 說(shuō)明

三、API接口