GetPlayInfo - ApsaraVideo VOD - Alibaba Cloud Documentation Center

Queries the playback URL of a video or audio file by its ID.

Operation Description

You can use the ID of a media file to query the playback URL of the file. After you integrate ApsaraVideo Player SDK for URL-based playback or a third-party player, you can use the obtained playback URLs to play audio and video files.
Only videos in the Normal state can be played. The Status parameter in the response indicates the status of the video. For more information, see Overview.
If video playback fails, you can call the GetMezzanineInfo operation to check whether the video source information is correct.

QPS limits

You can call this operation up to 360 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limit on API operations.

Authorization information

The following table is the authorization information corresponding to the API, which can be found in the RAM permission policy statement.Action Used in the element to grant the RAM user or RAM role permission to call this API. The specific instructions are as follows:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All resources is used in the Resource type column of the operation.
Condition keyword: refers to the condition keyword defined by the cloud product itself.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operate	access level	Resource type	conditional keyword	Association operation
vod:GetPlayInfo	Read	VOD acs:vod::{#accountId}:/*	without	without

Request parameters

Parameter	Type	Required	Description	Example
VideoId	string	Yes	The ID of the audio or video file. You can use one of the following methods to obtain the ID of the file: Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Media Files > Audio/Video. On the Video and Audio page, you can view the ID of the audio or video file. This method is applicable to files that are uploaded by using the ApsaraVideo VOD console. Obtain the value of the VideoId parameter when you call the CreateUploadVideo operation to upload files. Obtain the value of the VideoId parameter by calling the SearchMedia operation. This method is applicable to files that have been uploaded.	93ab850b4f654b6e91d24d81d44****
Formats	string	No	The format of the media stream. Separate multiple formats with commas (,). Valid values: mp4 m3u8 mp3 mpd NoteBy default, ApsaraVideo VOD returns video streams in all the preceding formats. However, video streams in the MPD format are returned only if the MPD container format is specified in the transcoding template. For more information, see the Container parameter in the TranscodeTemplate table.	mp4,m3u8
AuthTimeout	long	No	The validity period of the playback URL. Unit: seconds. If the OutputType parameter is set to cdn: This parameter takes effect only if URL authentication is enabled. Otherwise, the playback URL does not expire. Minimum value: 1. Maximum value: unlimited. Default value: The default validity period that is specified in URL authentication is used. If the OutputType parameter is set to oss: This parameter takes effect only when the ACL of the Object Storage Service (OSS) bucket is private. Otherwise, the playback URL does not expire. Minimum value: 1. Maximum value: 2592000 (30 days). This limit is imposed to reduce security risks of the origin server. Default value: 3600.	1800
OutputType	string	No	The type of the output URL. Default value: oss. Valid values: oss cdn	cdn
StreamType	string	No	The type of the media stream. Separate multiple types with commas (,). Valid values: video audio By default, video and audio streams are returned.	video
ReAuthInfo	string	No	The CDN reauthentication configuration. The value is a JSON string. If CDN reauthentication is enabled, you can use this parameter to specify the UID and rand fields for URL authentication. For more information, see URL authentication.	{"uid":"12345","rand":"abckljd"}
Definition	string	No	The quality of the video stream. Separate multiple qualities with commas (,). Valid values: FD: low definition LD: standard definition SD: high definition HD: ultra-high definition OD: original definition 2K: 2K 4K: 4K SQ: standard sound quality HQ: high sound quality AUTO: adaptive bitrate NoteBy default, ApsaraVideo VOD returns video streams in all preceding qualities. However, video streams for adaptive bitrate streaming are returned only if the PackageSetting parameter is specified in the transcoding template. For more information, see the PackageSetting parameter in the TranscodeTemplate table.	LD
ResultType	string	No	The type of the data to return. Default value: Single. Valid values: Single: Only one latest transcoded stream is returned for each quality and format. Multiple: All transcoded streams are returned for each quality and format.	Single
PlayConfig	string	No	The custom playback configuration. The value is a JSON string. For more information, see PlayConfig. Note If you do not specify PlayConfig or `PlayDomain` in PlayConfig, the default domain name configured in ApsaraVideo VOD is used in this operation. If no default domain name is configured, the domain names are queried in reverse chronological order based on the time when the domain names were modified. The domain name that was last modified is used as the streaming domain name. To prevent domain name issues, we recommend that you specify the default streaming domain name. You can log on to the ApsaraVideo VOD console and choose Configuration Management > Media Management > Storage > Manage > Origin Domain Name to set the default streaming domain name. Note If the `EncryptType` parameter in PlayConfig is set to `AliyunVoDEncryption`, the playback URL of the stream encrypted by using proprietary cryptography is not returned to ensure video security. If you want to return such URL, you must set the `ResultType` parameter to `Multiple`.	{"PlayDomain":"vod.test_domain","XForwardedFor":"yqCD7Fp1uqChoVj/sl/p5Q==","PreviewTime":"20","MtsHlsUriToken":"yqCD7Fp1uqChoVjslp5Q"}
AdditionType	string	No	The URL of the masked live comment data. Set the value to danmu. NoteThis parameter takes effect only when the outputType parameter is set to cdn.	danmu

Response parameters

Parameter	Type	Description	Example
	object	The returned result.
RequestId	string	The ID of the request.	F552E596-967D-5500-842F-17E6364****
VideoBase	object	The basic information about the audio or video file.
CreationTime	string	The time when the audio or video file was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.	2017-06-26T06:38:48Z
Status	string	The status of the audio or video file. For more information about the value range and description, see the Status table.	Normal
VideoId	string	The ID of the media file.	93ab850b4f654b6e91d24d81d44****
CoverURL	string	The thumbnail URL of the audio or video file.	http://example.aliyundoc.com/sample.jpg?auth_key=2333232-atb****
Duration	string	The duration of the audio or video file. Unit: seconds.	3.1667
Title	string	The title of the audio or video file.	ApsaraVideo VOD
MediaType	string	The type of the media file. Valid values: video audio	video
DanMuURL	string	The URL of the masked live comment data.	http://example.aliyundoc.com/**?auth_key=abdf2123-6783232**
PlayInfoList	array	The information about the audio or video stream.
	object	Details of the audio or video file.
CreationTime	string	The time when the audio or video file was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.	2022-04-18T07:37:15Z
Status	string	The status of the media stream. Valid values: Normal Invisible	Normal
Specification	string	The specifications of transcoded audio and video streams. For more information about the valid values, see Output specifications.	H264.LD
NarrowBandType	string	The type of Narrowband HD transcoding. Valid values: 0: regular 1.0: Narrowband HD 1.0 2.0: Narrowband HD 2.0 This parameter is returned only when a quality that is available in the built-in Narrowband HD 1.0 transcoding template is specified. For more information, see the Definition parameter in the TranscodeTemplate table.	0
Height	long	The height of the media stream. Unit: pixels.	640
Bitrate	string	The bitrate of the media stream. Unit: Kbit/s.	450.878
ModificationTime	string	The update time. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.	2022-04-20T06:32:19Z
WatermarkId	string	The ID of the watermark that is associated with the media stream.	dgfn26457856****
Encrypt	long	Indicates whether the video stream was encrypted. Valid values: 0: no 1: yes	1
Definition	string	The quality of the video stream. Valid values: FD: low definition LD: standard definition SD: high definition HD: ultra-high definition OD: original definition 2K: 2K 4K: 4K SQ: standard sound quality HQ: high sound quality AUTO: adaptive bitrate	LD
EncryptType	string	The encryption type of the media stream. Valid values: AliyunVoDEncryption: Alibaba Cloud proprietary cryptography HLSEncryption: HTTP Live Streaming (HLS) encryption NoteIf the encryption type is AliyunVoDEncryption, only ApsaraVideo Player SDK can be used to play videos.	AliyunVoDEncryption
StreamType	string	The type of the media stream. If the media stream is a video stream, the value is video. If the media stream is an audio-only stream, the value is audio.	video
JobId	string	The ID of the media transcoding job. This ID uniquely identifies a media stream.	80e9c6580e754a798c3c19c59b16****
Size	long	The size of the media stream. Unit: bytes.	418112
Width	long	The width of the media stream. Unit: pixels.	360
Fps	string	The frame rate of the media stream. Unit: frames per second.	25
Duration	string	The duration of the media stream. Unit: seconds.	9.0464
PlayURL	string	The playback URL of the video stream.	https://example.aliyundoc.com/d52ee123f331466aabf6ab32a93d**/a777f9e24e6e47a2a942467d5c38ea37-8ee8e04293c6657fdda282bc422704**.m3u8
Format	string	The format of the media stream. If the media file is a video file, the valid values are mp4 and m3u8. If the media file is an audio-only file, the value is mp3.	m3u8
HDRType	string	The HDR type of the media stream. Valid values: HDR HDR10 HLG DolbyVision HDRVivid SDR+	HLG
BitDepth	integer	The color depth. This value must be an integer.	8

Example

Normal return example

JSONFormat

{
  "RequestId": "F552E596-967D-5500-842F-17E6364****",
  "VideoBase": {
    "CreationTime": "2017-06-26T06:38:48Z",
    "Status": "Normal",
    "VideoId": "93ab850b4f654b6e91d24d81d44****",
    "CoverURL": "http://example.aliyundoc.com/sample.jpg?auth_key=2333232-atb****",
    "Duration": "3.1667",
    "Title": "ApsaraVideo VOD\n",
    "MediaType": "video",
    "DanMuURL": "http://example.aliyundoc.com/****?auth_key=abdf2123-6783232****"
  },
  "PlayInfoList": [
    {
      "CreationTime": "2022-04-18T07:37:15Z",
      "Status": "Normal",
      "Specification": "H264.LD",
      "NarrowBandType": "0",
      "Height": 640,
      "Bitrate": "450.878",
      "ModificationTime": "2022-04-20T06:32:19Z",
      "WatermarkId": "dgfn26457856****",
      "Encrypt": 1,
      "Definition": "LD",
      "EncryptType": "AliyunVoDEncryption",
      "StreamType": "video",
      "JobId": "80e9c6580e754a798c3c19c59b16****",
      "Size": 418112,
      "Width": 360,
      "Fps": "25",
      "Duration": "9.0464",
      "PlayURL": "https://example.aliyundoc.com/d52ee123f331466aabf6ab32a93d****/a777f9e24e6e47a2a942467d5c38ea37-8ee8e04293c6657fdda282bc422704****.m3u8",
      "Format": "m3u8",
      "HDRType": "HLG",
      "BitDepth": 8
    }
  ]
}

Error codes

For a list of error codes, visit the API error center.

Change history

Change time

Summary of changes

Operate

2021-12-23

The response structure of the API operation has changed

Change item	Change content
Output Parameters	The response structure of the API operation has changed

2021-11-16

The response structure of the API operation has changed

Change item	Change content
Output Parameters	The response structure of the API operation has changed