[事件管理] 点播与下载

流媒体相关 API 文档

一、获取流媒体服务器地址接口（get_binding_server）

用于获取设备绑定的流媒体服务器地址（IP:端口格式），为后续「回放接口」提供请求域名基础，需先调用该接口获取地址后，再发起回放相关请求。

（一）请求说明

1. 请求URL

GET: https://vsaas.kalay.us/vsaas/api/v1/be?query={get_binding_server(udid:String!)} POST: https://vsaas.kalay.us/vsaas/api/v1/be/ 说明：支持GET和POST两种请求方式，推荐使用POST方式

2. 请求头（Header）

参数名	类型	必选	说明
Authorization	String	是	授权令牌，格式：Bearer {token}
Content-Type	String	是	固定值：application/json（POST方式必传）

3. 请求参数

参数名	类型	必选	位置	说明
udid	String	是	GraphQL参数 QUERY	设备UID，唯一标识设备的字符串

4. 请求体（POST 方式专用）

{ "query": "get_binding_server(udid:\"KJKWJK\")" }

（二）响应说明

1. 响应状态码

状态码	徽章	说明
200	成功	请求成功，返回流媒体服务器地址
400	参数错误	请求参数错误（如udid未传递或格式非法）
401	授权失败	授权令牌无效或过期

2. 响应参数说明

参数名	类型	说明
get_binding_server	String	流媒体服务器地址，格式：IP:端口（如127.0.0.1:8080）

3. 请求示例（curl）

POST方式请求（示例）

curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d '{"query": "get_binding_server(udid:\"KJKWJK\")"}' https://vsaas.kalay.us/vsaas/api/v1/be/

GET方式请求（示例）

curl -XGET -H 'Authorization: Bearer LKdkjlk8873BNN' "https://vsaas.kalay.us/vsaas/api/v1/be?query={get_binding_server(udid:\"KJKWJK\")}"

4. 响应示例（成功）

{ "data": { "get_binding_server": "127.0.0.1:8080" } }

二、回放接口（ask_media）

用于获取事件的媒体资源（视频、图片）访问地址，支持回放、下载、获取缩略图等操作，需使用「获取流媒体服务器地址」接口返回的地址（IP:端口）发起请求。

（一）请求说明

1. 请求URL

POST: {vsaas-domain}/vsaas_stream/api/v1/ask 说明：{vsaas-domain} 需替换为「获取流媒体服务器地址」接口返回的地址（格式：IP:端口），如127.0.0.1:8080

2. 请求头（Header）

参数名	类型	必选	说明
Authorization	String	是	授权令牌，格式：Bearer {token}
Original/Refer	String	否	来源域名（可选参数，根据实际场景传递）
Content-Type	String	是	固定值：application/json

3. 请求参数

参数名	类型	必选	位置	说明
device	String	是	GraphQL参数 MUTATION	设备UID（与「获取流媒体服务器地址」接口的udid一致）
timestamp	String	是	GraphQL参数 MUTATION	时间戳（毫秒）：播放场景取自事件列表的start_time_ts，缩略图场景取自事件列表的thumbnail
length	Int	是	GraphQL参数 MUTATION	时长（秒）：仅全时录像或ICON模式有效，其他场景填写0
mode	Enum	是	GraphQL参数 MUTATION	操作模式：ASK_EVENT（回放）、ASK_DOWNLOAD（下载）、ASK_ICON（获取图片）
role	String	否	GraphQL参数 MUTATION	仅Alexa场景使用，可选值：alexa，其他场景无需传递
media_type	Enum	否	GraphQL参数 MUTATION	媒体类型：默认hls，支持krf（仅特定场景使用）

4. 请求体（POST 方式专用）

MP4下载

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"8945446565656\",length:60,mode:ASK_DOWNLOAD){code,ret,url}}" }

HLS回放

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"8945645454\",length:60,mode:ASK_EVENT){code,ret,url}}" }

KRF格式（回放）

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"4548979798\",length:60,mode:ASK_EVENT,media_type:krf){code,ret,url}}" }

KRF格式（下载）

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"84545454544\",length:60,mode:ASK_DOWNLOAD,media_type:krf){code,ret,url}}" }

设备图片（ICON模式）

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"0000000000000\",length:0,mode:ASK_ICON){code,ret,url}}" }

事件图片（ICON模式）

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"54549952554\",length:0,mode:ASK_ICON){code,ret,url}}" }

Alexa设备图片（ICON模式）

{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"0000000000000\",length:0,mode:ASK_ICON,role:alexa){code,ret,url}}" }

（二）响应说明

1. 响应状态码

状态码	徽章	说明
200	成功	请求成功，返回媒体资源访问地址
400	参数错误	请求参数错误（如模式非法、时间戳格式错误、必填参数缺失）
401	授权失败	授权令牌无效或过期

2. 响应参数说明

参数名	类型	说明
code	String	状态码：0表示成功，其他值为异常
ret	String	资源标识（含文件名及验证参数，如timestamp、ticket）
url	String	媒体资源访问完整URL（需拼接授权参数后用于播放/下载）
created	String	资源创建时间（可选返回字段，格式以实际响应为准）

3. 请求示例（curl）

MP4下载（示例）

// 替换{vsaas-domain}为实际服务器地址，如127.0.0.1:8080 curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d 'mutation {ask_media(device:"udid",timestamp:"8945446565656",length:60,mode:ASK_DOWNLOAD){code,ret,url}}' {vsaas-domain}/vsaas_stream/api/v1/ask

HLS回放（示例）

curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d 'mutation {ask_media(device:"udid",timestamp:"8945645454",length:60,mode:ASK_EVENT){code,ret,url}}' {vsaas-domain}/vsaas_stream/api/v1/ask

KRF格式回放（示例）

curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d 'mutation {ask_media(device:"udid",timestamp:"4548979798",length:60,mode:ASK_EVENT,media_type:krf){code,ret,url}}' {vsaas-domain}/vsaas_stream/api/v1/ask

事件图片获取（示例）

curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d 'mutation {ask_media(device:"udid",timestamp:"54549952554",length:0,mode:ASK_ICON){code,ret,url}}' {vsaas-domain}/vsaas_stream/api/v1/ask

4. 响应示例（成功）

MP4格式（下载）

{ "data": { "ask_media": { "code": "0", "ret": "44be325343e4219fed9372c277c71355e81f32da.mp4?timestamp=1533612816&ticket=b52c44f8f764432814fd2f93962ab7d881ec3e07", "url": "http://192.168.55.10:8080/media/44be325343e4219fed9372c277c71355e81f32da.mp4?timestamp=1533612816&ticket=b52c44f8f764432814fd2f93962ab7d881ec3e07" } } }

HLS格式（回放）

{ "data": { "ask_media": { "code": "0", "ret": "188c4e7810fd12303121c2282b1213c12f94421b.m3u8", "url": "http://192.168.55.10:8080/media/188c4e7810fd12303121c2282b1213c12f94421b.m3u8" } } }

KRF格式（回放/下载）

{ "data": { "ask_media": { "code": "0", "ret": "1565666774000_D15967E.krf?timestamp=1565667010961637000&ticket=6cc3057f0d5942d752956526d92a22dbe274ec9b", "url": "http://192.168.55.10:8080/media/1565666774000_D15967E.krf?timestamp=1565667010961637000&ticket=6cc3057f0d5942d752956526d92a22dbe274ec9b" } } }

ICON格式（图片）

{ "data": { "ask_media": { "code": "0", "ret": "44be325343e4219fed9372c277c71355e81f32da.jpg?timestamp=1533612816&ticket=b52c44f8f764432814fd2f93962ab7d881ec3e07", "url": "http://192.168.55.10:8080/media/44be325343e4219fed9372c277c71355e81f32da.jpg?timestamp=1533612816&ticket=b52c44f8f764432814fd2f93962ab7d881ec3e07" } } }

1. 接口依赖：必须先调用「获取流媒体服务器地址」接口获取{vsaas-domain}，再发起本接口请求，否则会导致请求失败

2. 回放测试：获取HLS格式的m3u8地址后，需拼接授权参数才能播放，格式如下：

https://asia-vpstream01-tutk-stg.kalay.us/vsaas_stream/api/v1/media/1b8296bca019c424711b00bf504c2be8bf41efe9.m3u8?access_token=Bearer%20{token}&role=android

• 替换 {token} 为实际的VSAAS授权令牌，若token包含特殊字符需做URL编码（如空格替换为%20）

• role可选值：android、ios、alexa，需根据实际客户端类型传递

3. 下载测试：获取MP4/KRF格式的下载地址后，需拼接授权参数才能下载，格式如下：

https://asia-vpstream01-tutk-stg.kalay.us/vsaas_stream/api/v1/media/90420c7141132082eae41d51baa64aab5c1a952f.mp4?timestamp=1728639352826274766&ticket=3c34a064365628bd4132a0572ef8bf62a72b0c62&access_token=Bearer%20{token}

• 直接使用该URL发起GET请求即可下载媒体文件

• 下载地址有效期以实际业务规则为准，建议获取后及时使用

4. 特殊说明：

• KRF格式仅支持特定场景使用，需提前确认服务器是否支持该格式

• ICON模式下length必须填写0，timestamp传递0表示获取设备默认图片，传递事件thumbnail时间戳表示获取事件关联图片

• Alexa场景需额外传递role=alexa参数，否则可能导致权限验证失败