Playlists in VodAppServer let you group ordered video collections, such as short-form dramas, for sequential playback and episodic display.
To call the ApsaraVideo VOD entity class and playlist class APIs, you must submit a ticket to be added to the allowlist.
-
Playlist: An ordered collection of videos, such as a short-form drama. For example, 10 ordered media assets (VideoIds) form a short-form drama playlist for sequential playback or episodic display.
-
Entity: An ApsaraVideo VOD storage capability that stores custom business information for media assets, such as cover images and tags, in
key-valueformat.
Playlist data structure
A playlist is a preset entity class in ApsaraVideo VOD.
|
Name |
Type |
Required |
Description |
|
PlaylistName |
string |
Yes |
The name of the playlist. |
|
PlaylistDescribe |
string |
No |
The description of the playlist. |
|
PlaylistStatus |
enum |
No |
The status of the playlist. Valid values:
|
|
PlaylistTags |
String |
No |
The tags of the playlist, separated by commas. |
|
PlaylistCoverUrl |
String |
No |
The URL of the playlist's cover image. |
|
PlaylistOrderBy |
String |
Yes |
The sorting rule for the playlist. Valid values: ● asc (default) Videos in the playlist are displayed in ascending or descending order based on the SortKey parameter value. |
|
Total |
Integer |
Yes |
The number of media assets in the playlist. |
|
PlaylistExtension |
String |
No |
Extension information in a JSON string, used to configure preview videos and other features. |
|
CreateTime |
String |
Yes |
The time when the playlist was created. |
|
ModifyTime |
String |
Yes |
The time when the playlist was last modified. |
|
PlaylistId |
String |
Yes |
The ID of the playlist. |
Playlist video structure
A playlist video associates a playlist with a media asset.
|
Name |
Type |
Required |
Description |
|
PlaylistId |
EntityMediaId |
Yes |
The ID of the playlist to which the video belongs. |
|
VideoId |
NormalMedia, single value |
Yes |
The media asset ID of the video in the playlist. |
|
SortKey |
Double |
Yes |
The sorting value, used for ordered display. |
|
Title |
String |
No |
The default title of the media asset. You can also customize it in the playlist. |
|
Description |
String |
No |
The default description of the media asset. You can also customize it in the playlist. |
|
CoverUrl |
String |
No |
The default cover image of the media asset. You can also customize it in the playlist. |
Example of creating a playlist
API endpoint: POST /appServer/createPlaylist.
Request parameters:
{
"playlistName": "Featured Short-form Dramas",
"playlistDescribe": "Most popular short-form dramas of 2024",
"playlistTags": "Romance,Urban,Popular",
"playlistCoverUrl": "IMAGE_ID",
"playlistVideos": "[{\"VideoId\":\"video1\",\"Title\":\"Episode 1\"}]"
}Parameter description:
|
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, separated by commas. |
|
playlistCoverUrl |
String |
No |
The URL of the playlist's cover image. |
|
playlistVideos |
String |
No |
The list of media assets in the playlist, in a JSON string. |
Extended capabilities
Playlist cover image
The playlistCoverUrl field supports an image asset ID (ImageId). AppServer automatically converts it into an accessible URL. You can also retrieve the full URL by calling the getPlaylistInfo API.
Video playback credential
For a video in a playlist, a JSON Web Token (JWT) playback credential (playAuth) is generated locally based on the ApsaraVideo VOD PlayKey. This eliminates the need to call GetVideoPlayAuth. The client can play the video directly using videoId + playAuth.
Preview effect
To enable a preview effect, configure the playlistExtension parameter with JSON data that includes a previewVideoId.
Configuration example:
{
"previewVideoId": "f0d8a2b3ce8d71f0bf8e45******0402"
}