API guide-ApsaraVideo VOD(VOD)-阿里云帮助中心

Playlist management

Create a playlist

API endpoint: POST /appServer/createPlaylist.

Request parameters:

{
  "playlistName": "Featured Short Plays Collection",
  "playlistDescribe": "The most popular short plays of 2024",
  "playlistTags": "Romance,Urban,Popular",
  "playlistCoverUrl": "IMAGE_ID",
  "playlistVideos": "[{\"VideoId\":\"video1\",\"Title\":\"Episode 1\"}]"
}

Parameters:

Name	Type	Required	Description
playlistName	String	Yes	The name of the playlist.
playlistDescribe	String	No	The description of the playlist.
playlistTags	String	No	The tags of the playlist. Separate multiple tags with commas.
playlistCoverUrl	String	No	The cover URL of the playlist.
playlistVideos	String	No	The list of media assets in the playlist. This is a JSON string.

Response example:

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

Delete playlists

API endpoint: POST /appServer/deletePlaylists.

Request parameters:

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

Parameters:

Name

Type

Required

Description

playlistIds

String

Yes

The IDs of the playlists. Separate multiple IDs with commas.

forceDelete

Boolean

No

Whether to force delete the playlists. Valid values:

true
false (default)

Note

If forceDelete is set to false, only empty playlists can be deleted. If forceDelete is set to true, playlists that contain videos can also be deleted. Deleting a playlist does not delete the associated media assets.

Get playlist details

API endpoint: POST /appServer/getPlaylist.

Request parameters:

{
  "playlistId": "pl_xxx"
}

Response example:

{
  "playlistId": "pl_xxx",
  "playlistName": "Featured Short Plays Collection",
  "playlistDescribe": "The most popular short plays of 2024",
  "playlistStatus": "Normal",
  "playlistTags": "Romance,Urban,Popular",
  "playlistCoverUrl": "https://xxx.oss.com/cover.jpg",
  "createTime": "2025-01-01T00:00:00Z",
  "playlistVideos": [
    {
      "videoId": "video1",
      "title": "Episode 1",
      "coverUrl": "https://xxx.oss.com/video1.jpg",
      "sortKey": 1
    }
  ]
}

Get a list of playlists

API endpoint: POST /appServer/getPlaylists.

Request parameters:

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

Parameters:

Name	Type	Required	Description
pageNo	String	Yes	The page number of the returned page.
pageSize	String	No	The number of entries per page. The default value is 10.
sortBy	String	No	The sorting rule for the playlist list, in the format of SortItem:SortOrder. Valid values for SortOrder: ● asc (default) ● desc

Update the basic information of a playlist

API endpoint: POST /appServer/updatePlaylistBasicInfo.

Request parameters:

{
  "playlistId": "pl_xxx",
  "playlistName": "Super Popular Short Plays",
  "playlistDescribe": "Latest Popular Short Plays Collection",
  "playlistStatus": "Normal",
  "playlistTags": "Hot,Recommended",
  "playlistCoverUrl": "new_image_id"
}

Parameters:

Name	Type	Required	Description
playlistId	String	Yes	The ID of the playlist.
playlistName	String	No	The name of the playlist.
playlistDescribe	String	No	The description of the playlist.
playlistStatus	String	No	The status of the playlist. Valid values: Normal Disabled
playlistTags	String	No	The tags of the playlist. Separate multiple tags with commas.
playlistCoverUrl	String	No	The cover URL of the playlist.

Add videos to a playlist

API endpoint: POST /appServer/addPlaylistVideos.

Request parameters:

{
  "playlistId": "pl_xxx",
  "preVideoId": "video1",
  "playlistVideos": "[{\"VideoId\":\"video2\",\"Title\":\"Episode 2\",\"Description\":\"Plot summary\",\"CoverUrl\":\"image_id\"}]"
}

Parameters:

Name	Type	Required	Description
playlistId	String	Yes	The ID of the playlist.
preVideoId	String	No	The ID of the preceding media asset. If this parameter is left empty, the new video is appended to the end of the playlist.
playlistVideos	String	Yes	The list of media assets to add to the playlist. This is a JSON string.

Delete videos from a playlist

API endpoint: POST /appServer/deletePlaylistVideos.

Request parameters:

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

Note

This operation only disassociates the media asset from the playlist. The media asset itself is not deleted.

Update the video list of a playlist

API endpoint: POST /appServer/updatePlaylistVideos.

Request parameters:

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

Get playlist details

API endpoint: POST /appServer/getPlaylistInfo?playListId=pl_xxx.

Response example:

{
  "code": 0,
  "httpCode": "200",
  "success": true,
  "data": {
    "playlistId": "pl_xxx",
    "playlistName": "Featured Short Plays Collection",
    "playlistCoverUrl": "https://xxx.oss.com/cover.jpg",
    "playlistVideos": [
      {
        "videoId": "video1",
        "title": "Episode 1",
        "playAuth": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "coverUrl": "https://xxx.oss.com/video1.jpg"
      }
    ]
  }
}

Note

When you retrieve playlist details:

A playAuth playback credential is generated automatically.
The cover image media asset ImageId is converted to an accessible URL automatically.
If playListId is not specified, the details of the first playlist are returned.

Get a list of playlists

API endpoint: POST /appServer/getPlaylistVideos.

Request parameters:

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

Note

When you retrieve a list of playlists:

Each playlist includes the first video as a preview. The preview includes a playback credential.
The cover image media asset ImageId is automatically converted to an accessible URL.

Media processing

Submit a transcoding job

API endpoint: POST /submitTransCodeJob?videoId=xxx&templateGroupId=xxx.

Parameters:

Name	Type	Required	Description
videoId	String	Yes	The ID of the media asset.
templateGroupId	String	Yes	The ID of the transcoding template group. For more information about how to create and obtain a transcoding template group, see Transcoding template groups.

System API operations

Health check

API endpoint: GET/POST /appServer/health.

Response example:

{
  "code": 0,
  "httpCode": "200",
  "success": true,
  "message": "Service responded successfully"
}

Error codes

Service error codes

Error code	Description	Solution
0	Success.	-
10001	Invalid parameter.	Check the format of the request parameters.
10002	Parameter is empty.	Provide the required parameters.
10003	Incorrect parameter type.	Check the parameter type.
10004	Missing parameter.	Provide the missing parameter.
40001	Internal system error.	Check the logs for troubleshooting.