[事件管理] 点播与下载

星空无限传媒xk8027-高清全集免费看

一、接口总览

接口名称	功能描述	请求方式	授权方式	接口版本
获取流媒体服务器地址（get_binding_server）	获取设备绑定的流媒体服务器地址（IP:端口），为回放接口提供域名基础	GET / POST	JWT / Bearer Token 授权	v1
回放接口（ask_media）	获取事件的媒体资源（视频、图片）访问地址，支持回放、下载、获取缩略图	POST	JWT / Bearer Token 授权	v1

二、获取流媒体服务器地址接口（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方式

说明：udid为设备唯一标识，需在GraphQL查询语句中指定。

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\")" }

说明：POST方式需将GraphQL查询语句放在request body的query字段中，参数值需使用双引号包裹并转义。

（二）响应说明

1. 响应状态码

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

2. 响应数据结构

{ "data": { "get_binding_server": "String" // 流媒体服务器地址（IP:端口格式） } }

3. 响应参数说明

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

（三）接口示例

1. 请求示例（curl）

POST方式请求（示例）

curl --location --request POST 'https://vsaas.kalay.us/vsaas/api/v1/be/' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "get_binding_server(udid:\"KJKWJK\")" }'

GET方式请求（示例）

curl --location --request GET 'https://vsaas.kalay.us/vsaas/api/v1/be?query={get_binding_server(udid:"KJKWJK")}' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json'

2. 响应示例（成功）

服务器地址响应（示例）

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

设备图片（ICON模式）

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

说明：不同操作模式下参数取值不同，ICON模式下length必须为0，timestamp传0表示获取设备默认图片。

（二）响应说明

1. 响应状态码

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

2. 响应数据结构

{ "data": { "ask_media": { "code": "String", // 状态码：0表示成功，其他值为异常 "ret": "String", // 资源标识（含文件名及验证参数） "url": "String", // 媒体资源访问完整URL "created": "String" // 资源创建时间（可选） } } }

3. 响应参数说明

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

（三）接口示例

1. 请求示例（curl）

MP4下载（示例）

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

HLS回放（示例）

curl --location --request POST '{vsaas-domain}/vsaas_stream/api/v1/ask' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"8945645454\",length:60,mode:ASK_EVENT){code,ret,url}}" }'

事件图片获取（示例）

curl --location --request POST '{vsaas-domain}/vsaas_stream/api/v1/ask' \ --header 'Authorization: Bearer LKdkjlk8873BNN' \ --header 'Content-Type: application/json' \ --data-raw '{ "query": "mutation {ask_media(device:\"udid\",timestamp:\"54549952554\",length:0,mode:ASK_ICON){code,ret,url}}" }'

2. 响应示例（成功）

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

媒体资源访问说明

获取HLS格式的m3u8地址后，需拼接授权参数才能播放，格式：
https://{domain}/media/{filename}.m3u8?access_token=Bearer%20{token}&role=android
获取MP4/KRF下载地址后，直接拼接access_token参数发起GET请求即可下载，地址有效期以实际业务规则为准。

四、错误码说明

错误码	错误描述	解决方案
`400`	Bad Request	检查GraphQL查询语法是否正确，参数格式是否合法（如timestamp是否为毫秒级字符串、mode是否为合法枚举值）；必填参数是否完整传递
`401`	Unauthorized	检查token是否有效、未过期，授权格式是否正确（Bearer前缀是否完整）；重新获取有效的授权令牌
`500`	Internal Server Error	服务器内部错误，请联系技术支持排查；确认流媒体服务器地址是否正确、服务是否正常运行

五、注意事项

调用ask_media接口前，必须先调用get_binding_server获取流媒体服务器地址，否则请求会失败；
get_binding_server接口支持GET和POST两种请求方式，ask_media仅支持POST方式；
所有接口均需要授权访问，需在请求头中携带有效的Bearer Token，否则会返回401错误；
KRF格式仅支持特定场景使用，需提前确认服务器是否支持该格式；ICON模式下length必须填写0；
接口调用频率限制：单设备每分钟最多调用30次，超出限制会返回429错误，需等待1分钟后重试；
媒体资源访问URL有效期为10分钟，过期后需重新调用ask_media接口获取新地址；
Alexa场景需额外传递role=alexa参数，否则可能导致权限验证失败；
若需调试接口，可使用官方提供的Postman集合（点击下载），包含所有接口的请求示例和环境配置。