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

Description

You 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. For more information, see Obtain playback URLs to play videos.

QPS limit

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 limits on API operations in ApsaraVideo VOD.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes GetPlayInfo

The operation that you want to perform. Set the value to GetPlayInfo.

VideoId String Yes 93ab850b4f654b6e91d24d81d44****

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.
Formats String No mp4,m3u8

The format of the media stream. Separate multiple formats with commas (,). Valid values:

  • mp4
  • m3u8
  • mp3
  • mpd
Note By 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 configured in the transcoding template. For more information, see the Container parameter in the TranscodeTemplate table.
AuthTimeout Long No 1800

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.
    • Default value: 3600.
OutputType String No cdn

The type of the output URL. Default value: cdn. Valid values:

  • oss: OSS URL
  • cdn: CDN URL
StreamType String No video

The type of the media stream. Separate multiple types with commas (,). Valid values:

  • video
  • audio

By default, both video and audio streams are returned.

ReAuthInfo String No {"uid":"12345","rand":"abckljd"}

The CDN reauthentication configuration. The value is a JSON string. If CDN reauthentication is enabled, you can use this parameter to set the UID and rand fields for URL authentication. For more information, see URL authentication.

Definition String No LD

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
Note By default, ApsaraVideo VOD returns video streams in all the preceding qualities. However, video streams for adaptive bitrate streaming are returned only if the PackageSetting parameter is set in the transcoding template. For more information, see the PackageSetting parameter in the TranscodeTemplate table.
ResultType String No Single

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.
PlayConfig String No {"PlayDomain":"vod.test_domain","XForwardedFor":"yqCD7Fp1uqChoVj/sl/p5Q==","PreviewTime":"20","MtsHlsUriToken":"yqCD7Fp1uqChoVjslp5Q"}

The custom playback configuration. The value is a JSON string. For more information, see PlayConfig.

Note
  • If you do not set 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 avoid domain name issues, we recommend that you set 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.
  • If the EncryptType parameter in PlayConfig is set to AliyunVoDEncryption, the playback URL of the stream encrypted by using proprietary cryptography is not returned by default to ensure video security. If you need to return such URL, you must set the ResultType parameter to Multiple.
AdditionType String No danmu

The URL of the masked live comment data. Value: danmu.

Note This parameter takes effect only when the outputType parameter is set to cdn.

Response parameters

Parameter Type Example Description
RequestId String F552E596-967D-5500-842F-17E6364****

The ID of the request.

VideoBase Object

The basic information about the audio or video file.

CreationTime String 2017-06-26T06:38:48Z

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.

Status String Normal

The status of the audio or video file. For more information about the value range and description, see the Status table.

VideoId String 93ab850b4f654b6e91d24d81d44****

The ID of the audio or video file.

CoverURL String http://example.aliyundoc.com/sample.jpg?auth_key=2333232-atb****

The thumbnail URL of the audio or video file.

Duration String 3.1667

The duration of the audio or video file. Unit: seconds.

Title String ApsaraVideo VOD

The title of the audio or video file.

MediaType String video

The type of the media file. Valid values:

  • video
  • audio
DanMuURL String http://example.aliyundoc.com/****?auth_key=abdf2123-6783232****

The URL of the masked live comment data.

PlayInfoList Array of PlayInfo

The information about the audio or video stream.

PlayInfo
CreationTime String 2022-04-18T07:37:15Z

The time when the stream URL was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Status String Normal

The status of the media stream. Valid values:

  • Normal
  • Invisible
Specification String H264.LD

The specifications of transcoded audio and video streams. For more information about the valid values, see Output specifications.

NarrowBandType String 0

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.

Height Long 640

The height of the media stream. Unit: pixels.

Bitrate String 450.878

The bitrate of the media stream. Unit: Kbit/s.

ModificationTime String 2022-04-20T06:32:19Z

The time when the stream URL was updated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

WatermarkId String dgfn26457856****

The ID of the watermark that is associated with the media stream.

Encrypt Long 1

Indicates whether the video stream was encrypted. Valid values:

  • 0: no
  • 1: yes
Definition String LD

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
EncryptType String AliyunVoDEncryption

The encryption type of the media stream. Valid values:

  • AliyunVoDEncryption: Alibaba Cloud proprietary cryptography
  • HLSEncryption: HTTP Live Streaming (HLS) encryption
Note If the encryption type is AliyunVoDEncryption, only ApsaraVideo Player SDK can be used to play videos.
StreamType String video

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.

JobId String 80e9c6580e754a798c3c19c59b16****

The ID of the media transcoding job. This ID uniquely identifies a media stream.

Size Long 418112

The size of the media stream. Unit: bytes.

Width Long 360

The width of the media stream. Unit: pixels.

Fps String 25

The frame rate of the media stream. Unit: frames per second.

Duration String 9.0464

The duration of the media stream. Unit: seconds.

PlayURL String https://example.aliyundoc.com/d52ee123f331466aabf6ab32a93d****/a777f9e24e6e47a2a942467d5c38ea37-8ee8e04293c6657fdda282bc422704****.m3u8

The playback URL of the video stream.

Format String m3u8

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.
HDRType String HLG

The HDR type of the media stream. Valid values:

  • HDR
  • HDR10
  • HLG
  • DolbyVision
  • HDRVivid
  • SDR+
BitDepth Integer 8

The color depth. This value must be an integer.

Examples

Sample requests

http(s)://vod.cn-shanghai.aliyuncs.com/?Action=GetPlayInfo
&VideoId=93ab850b4f654b6e91d24d81d44****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<GetPlayInfoResponse>
    <VideoBase>
        <Status>Normal</Status>
        <VideoId>93ab850b4f654b6e91d24d81d44****</VideoId>
        <TranscodeMode>NoTranscode</TranscodeMode>
        <CreationTime>2022-04-18T07:37:15Z</CreationTime>
        <Title>ApsaraVideo VOD</Title>
        <MediaType>video</MediaType>
        <CoverURL>http://example.aliyundoc.com/sample.jpg?auth_key=2333232-atb****</CoverURL>
        <Duration>3.1667</Duration>
        <OutputType>cdn</OutputType>
    </VideoBase>
    <RequestId>F552E596-967D-5500-842F-17E6364****</RequestId>
    <PlayInfoList>
        <PlayInfo>
            <Status>Normal</Status>
            <StreamType>video</StreamType>
            <HDRType>HLG</HDRType>
            <Size>418112</Size>
            <Definition>LD</Definition>
            <Fps>25</Fps>
            <Specification>H264.LD</Specification>
            <ModificationTime>2022-04-20T06:32:19Z</ModificationTime>
            <Duration>9.0464</Duration>
            <Bitrate>450.878</Bitrate>
            <BitDepth>8</BitDepth>
            <Encrypt>0</Encrypt>
            <PreprocessStatus>UnPreprocess</PreprocessStatus>
            <Format>m3u8</Format>
            <NarrowBandType>0</NarrowBandType>
            <PlayURL>https://example.aliyundoc.com/d52ee123f331466aabf6ab32a93d****/a777f9e24e6e47a2a942467d5c38ea37-8ee8e04293c6657fdda282bc422704****.m3u8</PlayURL>
            <CreationTime>2022-04-20T06:32:14Z</CreationTime>
            <Height>640</Height>
            <Width>360</Width>
            <JobId>80e9c6580e754a798c3c19c59b16****</JobId>
        </PlayInfo>
    </PlayInfoList>
</GetPlayInfoResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

For a list of error codes, visit the API Error Center.

Common errors

The following table describes the common errors that this operation can return.

Error code

Error message

HTTP status code

Description

Forbidden.IllegalStatus

Status of the video is illegal. Current Status is %s.

403

The error message returned because the video status is invalid. %s indicates the current video status. Only videos in the Normal state can be played.

InvalidVideo.NotFound

The video does not exist.

404

The error message is returned because the video does not exist.

InvalidVideo.NoneStream

The video has no stream to play for the request parameter 'Formats: mp4, Definition: LD, StreamType: video'.

404

The error message returned because no transcoded stream that meets the specified filter criteria is available for playback. Check whether the transcoding configuration matches the filter criteria.

Forbidden.AliyunVoDEncryption

Currently only the AliyunVoDEncryption stream exists, you must use the Aliyun player to play or set the value of ResultType to Multiple.

403

The error message returned because only transcoded files that are encrypted by using Alibaba Cloud proprietary cryptography exist. You must use ApsaraVideo Player to play the files or set the ResultType parameter to Multiple.

SDKs

We recommend that you use a server-side SDK to call this operation. For more information about the sample code that is used to call this operation in various languages, see the following topics: