一、概述
本文档将描述VSaaS设备端推流相关核心接口，包括获取上传地址、推流（视频上传）、更新事件标签三个关键操作。设备端需先通过VSaaS Token认证，再依次完成推流地址获取、视频分片上传、事件标签补充等流程，最终实现视频数据的云端存储与管理。
前置条件：设备端需从第三方APP获取有效的VSaaS Token（stoken），用于接口身份校验。
二、API接口
（一）获取上传地址
设备端通过此接口获取视频推流地址，用于将事件视频或实时视频流上传至VSaaS云端，推流前需优先调用此接口。
1. 请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | GET |
| 请求URL | https://vsaas-domain/vsaas/api/v1/stream/stream_url/{UDID}?stoken={stoken}&starttime={timestamp}&protocol=upload&event_id={event_id}[&event_file={event_file}][&media_type={media_type}][&tags={tag}] |
| 请求头（Header） | 无额外要求，参数通过URL拼接传递 |
2. 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| UDID | String | 是 | 设备唯一标识（设备UID） |
| stoken | String | 是 | 推流用Token，从APP端获取 |
| event_id | String | 是 | 事件类型ID |
| starttime | String | 是 | 事件触发时间戳（秒级） |
| protocol | String | 是 | 固定值：upload |
| event_file | String | 否 | 关联的事件文件名称（可选） |
| media_type | Int | 否 | 媒体类型：0=hls，1=krf，4=mp4（默认按系统配置） |
| tags | String | 否 | 事件标签，多个标签用逗号分隔（如"门口,花园"） |
3. 响应说明
3.1 响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| contract_type | String | 存储类型："event"（事件存储）或 "fulltime"（全时存储） |
| url | String | 推流地址（含OTP临时授权码） |
| recording_max_kbps | Int | 最大推流码率（kbps） |
| video_max_fps | Int | 最大帧率（fps） |
| video_max_height | Int | 视频最大高度（像素） |
| video_max_width | Int | 视频最大宽度（像素） |
| message | String | 错误信息（成功时为空） |
| code | Int | 错误码：1=成功；-1001=参数无效；-1002=设备无效；-1003=绑定记录无效；-1004=合约无效；-1005=开始时间无效；-1006=开始时间格式错误；-3001=合约未找到 |
3.2 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回推流地址及配置信息 |
| 400 | 参数错误 | 必填参数缺失或格式错误 |
4. 接口示例
请求示例（curl）
curl -vvv "https://idc-stg-be-docker.kalay.us:8864/vsaas/api/v1/stream/stream_url/TC021LBP010000000001AAAAAAAAAAAAAAAAAAAA?stoken=dEmhotTRI7FG4ceJfZ1R7b6NwuJXhpclrGlm2LvkOguM4nPCjnZRN5zrltts-sPp0E5kdK_T6D9pJN5axFgnkX0QmiWfOm3-ybLmQy5Guwk=&protocol=upload&event_id=999&starttime=1562048846"
响应示例（成功）
{
"result": {
"url": "https://idc-stg-stream01.kalay.us:8080/post_stream/v1/TC021LBP010000000001AAAAAAAAAAAAAAAAAAAA?OTP=202E457ED959CA934F3A&stoken=dEmhotTRI7FG4ceJfZ1R7b6NwuJXhpclrGlm2LvkOguM4nPCjnZRN5zrltts-sPp0E5kdK_T6D9pJN5axFgnkX0QmiWfOm3-ybLmQy5Guwk=&event_id=999&starttime=1562048846",
"contract_type": "event",
"recording_max_kbps": 10,
"video_max_fps": 15,
"event_recording_max_length": 10,
"video_max_height": 360,
"video_max_width": 480
},
"message": "",
"code": 1
}
（二）推流（视频上传）
设备端使用「获取上传地址」接口返回的推流地址，以multipart/form-data格式将视频流（支持分片）上传至VSaaS云端，支持TS/MP4/JPG格式文件。
1. 请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | POST |
| 请求URL | 从「获取上传地址」接口返回的url（含OTP临时授权码） |
| 请求头（Header） | Content-Type: multipart/form-data; boundary={自定义边界值}（边界值需与请求体中一致） |
2. 请求参数
| 参数类型 | 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|---|
| URL参数 | OTP | String | 是 | 临时授权码，来自推流地址（每次推流唯一） |
| stoken | String | 是 | 推流用Token，与「获取上传地址」时一致 | |
| event_id | String | 是 | 事件类型ID，与「获取上传地址」时一致 | |
| starttime | String | 是 | 事件触发时间戳（秒级），与「获取上传地址」时一致 | |
| UDID | String | 是 | 设备唯一标识，与「获取上传地址」时一致 | |
| tags | String | 否 | 事件标签，多个标签用逗号分隔（可选补充） | |
| Form-Data参数（media_file） | file_start_time | String | 是 | 文件开始时间戳（毫秒级），需等于starttime*1000 |
| file_duration | String | 是 | 文件时长（毫秒级）；JPG格式填0 | |
| event_end | String | 是 | 事件结束标识：1=最后一个文件，0=后续还有文件 | |
| filename | String | 否 | 格式：{13位毫秒时间戳}_D{毫秒时长}[E].(ts/mp4/jpg)；E标识最后一个文件；优先级低于前三个参数 | |
| Content-Type | String | 是 | 文件类型：video/MP2T（TS）、video/mp4（MP4）、image/jpg（JPG） | |
| 请求体 | - | Binary | 是 | 视频/图片二进制数据；多文件需重复media_file字段分片上传 |
2.1 多文件上传说明
- 1. 分片视频（如TS文件）需为每个分片重复media_file字段，最后一个分片event_end设为1；
- 2. 已填写file_start_time、file_duration、event_end时，可省略filename，系统自动生成；
- 3. 分片时长建议一致（如5秒/片），便于后续回放和下载。
3. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 文件上传成功 |
| 400 | 参数错误 | Form-Data参数缺失或格式错误 |
| 403 | 授权失败 | OTP过期、stoken无效或推流地址失效 |
4. 接口示例
请求示例（curl）
curl -X POST \
"http://localhost:55550/post_stream/v1/DRUUA974YFRC9MPGU1XJ?stoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&starttime=1570237012&event_id=999&OTP=hahahaha" \
-H "Content-Type: multipart/form-data; boundary=cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac" \
-F "media_file=@1570237012000_D5000.ts;type=video/mp2t;file_start_time=1570237012000;file_duration=5000;event_end=0" \
-F "media_file=@1570237017000_D5000E.ts;type=video/mp2t;file_start_time=1570237017000;file_duration=5000;event_end=1"
请求体示例（Form-Data）
--cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac
Content-Disposition: form-data; name="media_file";file_start_time="1570011960000";file_duration="5000";event_end="0"
Content-Type: video/MP2T
[TS文件二进制数据]
--cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac
Content-Disposition: form-data; name="media_file";file_start_time="1570011965000";file_duration="5000";event_end="1"
Content-Type: video/MP2T
[TS文件二进制数据]
--cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac--
（三）更新事件标签
为已上传的事件视频添加标签，支持多个标签以逗号分隔，标签用于后续事件筛选和查询。
1. 请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | GET |
| 请求URL | https://vsaas-domain/vsaas/api/v1/stream/stream_event/{UDID}?stoken={stoken}&tags=a,b,c,d&starttime={timestamp} |
| 请求头（Header） | 无额外要求，参数通过URL拼接传递 |
2. 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| UDID | String | 是 | 设备唯一标识（与上传视频时一致） |
| stoken | String | 是 | 推流用Token，与上传视频时一致 |
| starttime | String | 是 | 事件触发时间戳（秒级），与上传视频时一致（唯一标识事件） |
| tags | String | 否 | 事件标签，多个标签用逗号分隔（如"门口,花园,异常"）；为空则清空标签 |
3. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 标签更新成功 |
| 400 | 参数错误 | UDID、stoken、starttime缺失或格式错误 |
4. 接口示例
请求示例（curl）
curl -vvv "https://vsaas-stg.kalay.us/vsaas/api/v1/stream/stream_event/TC021LBP010000000001AAAAAAAAAAAAAAAAAAAA?stoken=dEmhotTRI7FG4ceJfZ1R7b6NwuJXhpclrGlm2LvkOguM4nPCjnZRN5zrltts-sPp0E5kdK_T6D9pJN5axFgnkX0QmiWfOm3-ybLmQy5Guwk=&tags=a,b,c,d&starttime=1562048846"
