使用VodAppServer API構建播放清單與媒體服務 - ApsaraVideo for VOD

本文介紹VodAppServer的API介面。

播單管理

建立播單

介面地址：POST /appServer/createPlaylist。

請求參數：

{
  "playlistName": "精選短劇合集",
  "playlistDescribe": "2024年最受歡迎的短劇",
  "playlistTags": "愛情,都市,熱播",
  "playlistCoverUrl": "IMAGE_ID",
  "playlistVideos": "[{\"VideoId\":\"video1\",\"Title\":\"第1集\"}]"
}

參數說明：

名稱	類型	必填	描述
playlistName	String	是	播單名稱。
playlistDescribe	String	否	播單描述。
playlistTags	String	否	播單標籤，以逗號分隔。
playlistCoverUrl	String	否	播單封面地址。
playlistVideos	String	否	播單媒資列表，為JSON字串。

響應樣本：

{
  "playlistId": "pl_xxx",
  "requestId": "xxx"
}

刪除播單

介面地址：POST /appServer/deletePlaylists。

請求參數：

{
  "playlistIds": "pl_001,pl_002",
  "forceDelete": false
}

參數說明：

名稱

類型

必填

描述

playlistIds

String

是

播單ID，以逗號分隔。

forceDelete

Boolean

否

是否強制移除，取值：

true。
false（預設）。

說明

forceDelete參數為false時僅允許刪除空播單，為true時允許刪除含視頻的播單，刪除播單不會刪除相關媒資。

擷取播單詳情

介面地址：POST /appServer/getPlaylist。

請求參數：

{
  "playlistId": "pl_xxx"
}

響應樣本：

{
  "playlistId": "pl_xxx",
  "playlistName": "精選短劇合集",
  "playlistDescribe": "2024年最受歡迎的短劇",
  "playlistStatus": "Normal",
  "playlistTags": "愛情,都市,熱播",
  "playlistCoverUrl": "https://xxx.oss.com/cover.jpg",
  "createTime": "2025-01-01T00:00:00Z",
  "playlistVideos": [
    {
      "videoId": "video1",
      "title": "第1集",
      "coverUrl": "https://xxx.oss.com/video1.jpg",
      "sortKey": 1
    }
  ]
}

擷取播單列表

介面地址：POST /appServer/getPlaylists。

請求參數：

{
  "pageNo": "1",
  "pageSize": "10",
  "sortBy": "CreationTime:Desc"
}

參數說明：

名稱	類型	必填	描述
pageNo	String	是	播單列表分頁頁數。
pageSize	String	否	播單列表分頁每頁數量，預設值為10。
sortBy	String	否	播單列表定序，以冒號分隔，左邊為排序項，右邊為定序，取值： ● asc（預設）。 ● desc。

更新播單基本資料

介面地址：POST /appServer/updatePlaylistBasicInfo。

請求參數：

{
  "playlistId": "pl_xxx",
  "playlistName": "超級熱播短劇",
  "playlistDescribe": "最新熱播短劇精選",
  "playlistStatus": "Normal",
  "playlistTags": "熱門,推薦",
  "playlistCoverUrl": "new_image_id"
}

參數說明：

名稱	類型	必填	描述
playlistId	String	是	播單ID。
playlistName	String	否	播單名稱。
playlistDescribe	String	否	播單描述。
playlistStatus	String	否	播單狀態，取值： Normal。 Disabled。
playlistTags	String	否	播單標籤，以逗號分隔。
playlistCoverUrl	String	否	播單封面地址。

添加播單視頻

介面地址：POST /appServer/addPlaylistVideos。

請求參數：

{
  "playlistId": "pl_xxx",
  "preVideoId": "video1",
  "playlistVideos": "[{\"VideoId\":\"video2\",\"Title\":\"第2集\",\"Description\":\"劇情介紹\",\"CoverUrl\":\"image_id\"}]"
}

參數說明：

名稱	類型	必填	描述
playlistId	String	是	播單ID。
preVideoId	String	否	前置媒資ID，為空白則添加至末尾。
playlistVideos	String	是	添加的播單媒資列表，為JSON字串。

刪除播單視頻

介面地址：POST /appServer/deletePlaylistVideos。

請求參數：

{
  "playlistId": "pl_xxx",
  "videoIds": "video1,video2"
}

說明

僅刪除媒資與播單關聯，不刪除媒資本身。

更新播單視頻列表

介面地址：POST /appServer/updatePlaylistVideos。

請求參數：

{
  "playlistId": "pl_xxx",
  "videoIds": "video1,video2,video3"
}

擷取播單詳情

介面地址：POST /appServer/getPlaylistInfo?playListId=pl_xxx。

響應樣本：

{
  "code": 0,
  "httpCode": "200",
  "success": true,
  "data": {
    "playlistId": "pl_xxx",
    "playlistName": "精選短劇合集",
    "playlistCoverUrl": "https://xxx.oss.com/cover.jpg",
    "playlistVideos": [
      {
        "videoId": "video1",
        "title": "第1集",
        "playAuth": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "coverUrl": "https://xxx.oss.com/video1.jpg"
      }
    ]
  }
}

說明

擷取播單詳情時：

自動產生playAuth播放憑證。
封面圖媒資ImageId自動轉換為可訪問URL。
未傳playListId參數時將返回首個播單詳情。

擷取播單列表

介面地址：POST /appServer/getPlaylistVideos。

請求參數：

{
  "pageNo": "1",
  "pageSize": "10"
}

說明

擷取播單列表時：

每個播單包含首個視頻作為預覽（包含播放憑證）。
封面圖媒資ImageId自動轉換為可訪問URL。

ApsaraVideo for Media Processing

提交轉碼任務

介面地址：POST /submitTransCodeJob?videoId=xxx&templateGroupId=xxx。

參數說明：

名稱	類型	必填	描述
videoId	String	是	媒資ID。
templateGroupId	String	是	轉碼模板組ID，可參考轉碼模板組建立和擷取。

系統介面

健全狀態檢查

介面地址：GET/POST /appServer/health。

響應樣本：

{
  "code": 0,
  "httpCode": "200",
  "success": true,
  "message": "服務響應成功"
}

錯誤碼

業務錯誤碼

錯誤碼	說明	解決方案
0	成功。	-
10001	參數無效。	請檢查請求參數格式。
10002	參數為空白。	請補充必填參數。
10003	參數類型錯誤。	請檢查參數類型。
10004	參數缺失。	請補充缺失參數。
40001	系統內部錯誤。	請查看日誌排查。