一、接口總覽
| 接口名稱 | 功能描述 | 請求方式 | 授權(quán)方式 | 接口版本 |
|---|---|---|---|---|
| 獲取流媒體服務(wù)器地址（get_binding_server） | 獲取設(shè)備綁定的流媒體服務(wù)器地址（IP:端口），為回放接口提供域名基礎(chǔ) | GET / POST | JWT / Bearer Token 授權(quán) | v1 |
| 回放接口（ask_media） | 獲取事件的媒體資源（視頻、圖片）訪問地址，支持回放、下載、獲取縮略圖 | POST | JWT / Bearer Token 授權(quán) | v1 |
二、獲取流媒體服務(wù)器地址接口（get_binding_server）
用于獲取設(shè)備綁定的流媒體服務(wù)器地址（IP:端口），為后續(xù)「回放接口」提供請求域名基礎(chǔ)，需先調(diào)用該接口獲取地址后，再發(fā)起回放相關(guān)請求。
（一）請求說明
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為設(shè)備唯一標(biāo)識，需在GraphQL查詢語句中指定。2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：Bearer {token} |
Content-Type | String | 是 | 固定值：application/json（POST方式必傳） |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
udid | String | 是 | GraphQL參數(shù) QUERY | 設(shè)備UID，唯一標(biāo)識設(shè)備的字符串 |
4. 請求體（POST 方式專用）
{
"query": "get_binding_server(udid:\"KJKWJK\")"
}
說明：POST方式需將GraphQL查詢語句放在request body的query字段中，參數(shù)值需使用雙引號包裹并轉(zhuǎn)義。
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回流媒體服務(wù)器地址 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如udid未傳遞或格式非法） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"get_binding_server": "String" // 流媒體服務(wù)器地址（IP:端口格式）
}
}
3. 響應(yīng)參數(shù)說明
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
get_binding_server | String | 流媒體服務(wù)器地址，格式：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. 響應(yīng)示例（成功）
服務(wù)器地址響應(yīng)（示例）
{
"data": {
"get_binding_server": "127.0.0.1:8080"
}
}
三、回放接口（ask_media）
用于獲取事件的媒體資源（視頻、圖片）訪問地址，支持回放、下載、獲取縮略圖等操作，需使用「獲取流媒體服務(wù)器地址」接口返回的地址（IP:端口）發(fā)起請求。
（一）請求說明
1. 請求URL
POST: {vsaas-domain}/vsaas_stream/api/v1/ask
說明：{vsaas-domain} 需替換為「獲取流媒體服務(wù)器地址」接口返回的地址（格式：IP:端口），如127.0.0.1:8080
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：Bearer {token} |
Original/Refer | String | 否 | 來源域名（可選參數(shù)，根據(jù)實際場景傳遞） |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備UID（與「獲取流媒體服務(wù)器地址」接口的udid一致） |
timestamp | String | 是 | GraphQL參數(shù) MUTATION | 時間戳（毫秒）：播放場景取自事件列表的start_time_ts，縮略圖場景取自事件列表的thumbnail |
length | Int | 是 | GraphQL參數(shù) MUTATION | 時長（秒）：僅全時錄像或ICON模式有效，其他場景填寫0 |
mode | Enum | 是 | GraphQL參數(shù) MUTATION | 操作模式：ASK_EVENT（回放）、ASK_DOWNLOAD（下載）、ASK_ICON（獲取圖片） |
role | String | 否 | GraphQL參數(shù) MUTATION | 僅Alexa場景使用，可選值：alexa，其他場景無需傳遞 |
media_type | Enum | 否 | GraphQL參數(shù) 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}}"
}
設(shè)備圖片（ICON模式）
{
"query": "mutation {ask_media(device:\"udid\",timestamp:\"0000000000000\",length:0,mode:ASK_ICON){code,ret,url}}"
}
說明：不同操作模式下參數(shù)取值不同，
ICON模式下length必須為0，timestamp傳0表示獲取設(shè)備默認圖片。（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回媒體資源訪問地址 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如模式非法、timestamp格式錯誤、必填參數(shù)缺失） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"ask_media": {
"code": "String", // 狀態(tài)碼：0表示成功，其他值為異常
"ret": "String", // 資源標(biāo)識（含文件名及驗證參數(shù)）
"url": "String", // 媒體資源訪問完整URL
"created": "String" // 資源創(chuàng)建時間（可選）
}
}
}
3. 響應(yīng)參數(shù)說明
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
code | String | 狀態(tài)碼：0表示成功，其他值為異常 |
ret | String | 資源標(biāo)識（含文件名及驗證參數(shù)，如timestamp、ticket） |
url | String | 媒體資源訪問完整URL（需拼接授權(quán)參數(shù)后用于播放/下載） |
created | String | 資源創(chuàng)建時間（可選返回字段，格式以實際響應(yīng)為準(zhǔn)） |
（三）接口示例
1. 請求示例（curl）
MP4下載（示例）
// 替換{vsaas-domain}為實際服務(wù)器地址，如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}}"
}'
事件圖片獲?。ㄊ纠?/div>
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. 響應(yīng)示例（成功）
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地址后，需拼接授權(quán)參數(shù)才能播放，格式：https://{domain}/media/{filename}.m3u8?access_token=Bearer%20{token}&role=android
獲取MP4/KRF下載地址后，直接拼接access_token參數(shù)發(fā)起GET請求即可下載，地址有效期以實際業(yè)務(wù)規(guī)則為準(zhǔn)。
四、錯誤碼說明
| 錯誤碼 | 錯誤描述 | 解決方案 |
|---|---|---|
400 | Bad Request | 檢查GraphQL查詢語法是否正確，參數(shù)格式是否合法（如timestamp是否為毫秒級字符串、mode是否為合法枚舉值）；必填參數(shù)是否完整傳遞 |
401 | Unauthorized | 檢查token是否有效、未過期，授權(quán)格式是否正確（Bearer前綴是否完整）；重新獲取有效的授權(quán)令牌 |
500 | Internal Server Error | 服務(wù)器內(nèi)部錯誤，請聯(lián)系技術(shù)支持排查；確認流媒體服務(wù)器地址是否正確、服務(wù)是否正常運行 |
