GetPlayInfo - 获取音视频播放地址 - 视频点播

调用此接口并提供音视频ID即可获取播放地址，随后可使用阿里云播放器或第三方播放器（如系统原生、开源或自研播放器）播放音视频内容。

接口说明

请确保在使用该接口前，已充分了解视频点播产品的收费方式和价格。从点播的播放地址直接下载或播放视频将产生下行流量费用，未配置加速域名时请参见存储流出流量计费；已配置加速域名时请参见加速服务计费。如果您已开通了存储传输加速，则从点播的播放地址直接下载或播放视频还将涉及下载加速费用，计费详情请参见存储传输加速计费。
只有状态为正常（Status 字段值为 Normal）的视频才能正常播放。关于播放地址的播放说明及使用限制等更多信息，请参见音视频播放。
当视频播放异常时，您可以调用 GetMezzanineInfo 接口查询视频源文件信息是否正确。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
vod:GetPlayInfo	get	全部资源 ``	无	无

请求参数

名称	类型	必填	描述	示例值
VideoId	string	是	音/视频 ID，仅支持传入单个音/视频 ID。可通过以下方式获取：通过控制台上传的音/视频，可登录视频点播控制台，选择媒资库 > 音/视频查看音/视频 ID。通过 CreateUploadVideo 接口上传音/视频时，音/视频 ID 为返回参数 VideoId 的值。音/视频上传后，可通过 SearchMedia 接口查询音/视频 ID，为请求后返回参数 VideoId 的值。	93ab850b4f654b6e91d24d81d44****
Formats	string	否	媒体流格式。多个格式之间使用半角逗号（,）分隔。取值： mp4 m3u8 mp3 flv mpd 说明默认获取所有格式的流。 mpd 格式仅当转码模板中配置了`dash`封装格式时才会输出。更多详情，请参见Container：封装格式。	mp4,m3u8
AuthTimeout	long	否	设置播放地址的有效时间。单位：秒。当 OutputType 取值为 cdn 时：只有开启了 URL 鉴权，播放地址才会定期失效，否则会永久有效。URL 鉴权的开启及配置方法，请参见 URL 鉴权。最小值：1。最大值：无限制。默认值：未设置时，取值为 URL 鉴权中设置的默认有效时长。当 OutputType 取值为 oss 时：只有存储权限为私有，播放地址才会定期失效，否则会永久有效。最小值：1。最大值：为降低源站安全风险，当音视频存储在点播系统 Bucket 上时，最大值为 2592000（即 30 天），当音视频存储在 OSS 自有 Bucket 上时，最大值为 129600（即 36 小时）。如果此处设置的最大值不能满足您的需求，您可以设置 OutputType 为 cdn，通过设置 URL 鉴权来设置更长的有效期。默认值：未设置时，取值为 3600。	1800
OutputType	string	否	输出地址类型。取值： oss：回源地址。 cdn（默认）：加速地址。	cdn
StreamType	string	否	媒体流类型。多个类型之间用半角逗号（,）分隔。支持类型： video：视频。 audio：音频。默认获取所有类型的流。	video
ReAuthInfo	string	否	CDN 二次鉴权参数，为 JSON 字符串。当开启了 URL 鉴权的 A 方式鉴权功能时，可通过该参数设置鉴权 URL 的`uid`和`rand`，请参见鉴权方式 A 说明。	{"uid":"12345","rand":"abckljd"}
Definition	string	否	视频流清晰度。多个清晰度之间用半角逗号（,）分隔。取值： FD：流畅。 LD：标清。 SD：高清。 HD：超清 OD：原画。 2K：2K。 4K：4K。 SQ：普通音质。 HQ：高音质。 AUTO：自适应码率。说明默认获取所有清晰度的流。生成溯源水印时，本参数必填，需与溯源水印转码时所设置的清晰度保持一致。 AUTO 格式仅当转码模板中配置了转码打包时才会有该清晰度输出，请参见PackageSetting：转码打包设置。	LD
ResultType	string	否	返回数据类型。取值： Single（默认）：每种清晰度和格式只返回一路最新转码完成的流。 Multiple：每种清晰度和格式返回所有转码完成的流。	Single
PlayConfig	string	否	播放自定义设置。为 JSON 字符串，支持指定域名播放设置。参数构造详情，请参见 PlayConfig 。说明 PlayConfig 不设置或者其中`PlayDomain`不设置时，接口默认使用点播配置的默认域名；如果没有设置默认域名，则会根据域名的修改时间倒序查询，使用最新修改过的域名作为播放域名。为防止返回的不是想要的域名，建议设置默认播放域名（可登录视频点播控制台，选择配置管理 > 媒资管理配置 > 存储管理 > 管理 > 回源到此存储地址的域名设置默认播放域名）。当 PlayConfig 中的`EncryptType`参数设置为`AliyunVoDEncryption`时，为了保障您的视频安全，默认不返回私有加密流播放地址，若需要返回私有加密流播放地址，需要同时设置`ResultType`参数为`Multiple`。	{"PlayDomain":"vod.test_domain","XForwardedFor":"yqCD7Fp1uqChoVj/sl/p5Q==","PreviewTime":"20","MtsHlsUriToken":"yqCD7Fp1uqChoVjslp5Q"}
AdditionType	string	否	获取弹幕蒙版数据 URL 地址，取值：danmu。说明仅当`outputType`取值为`cdn`时才会生效。	danmu
Trace	string	否	用户自定义的数字水印信息。当`DigitalWatermarkType`取值为`TraceMark`时，通过传入本参数，可以为视频设置溯源水印的水印信息，并返回包含水印信息的视频流。仅支持传入英文字母、数字及中文字符，最多支持 1024 个字符。当`DigitalWatermarkType`取值为`CopyrightMark`时，`Trace`对应创建水印模板时所设置的水印文字。通过传入本参数，可以查询并返回指定水印文字的视频流。	test mark
DigitalWatermarkType	string	否	数字水印类型。取值： TraceMark：溯源水印。 CopyrightMark：版权水印。	TraceMark

返回参数

名称	类型	描述	示例值
	object	返回结果。
RequestId	string	请求 ID。	F552E596-967D-5500-842F-17E6364****
VideoBase	object	音/视频基本信息。
CreationTime	string	音/视频创建时间。格式为：yyyy-MM-ddTHH:mm:ssZ（UTC 时间）。	2017-06-26T06:38:48Z
Status	string	音/视频状态。各取值及描述，请参见Status：音视频状态。	Normal
VideoId	string	音/视频 ID。	93ab850b4f654b6e91d24d81d44****
CoverURL	string	音/视频封面地址。	http://example.aliyundoc.com/sample.jpg?auth_key=2333232-atb****
Duration	string	音/视频时长。单位：秒。	3.1667
Title	string	音/视频标题。	阿里云VOD
MediaType	string	媒体文件类型，取值： video：视频。 audio：纯音频。	video
DanMuURL	string	弹幕蒙版数据的地址。	http://example.aliyundoc.com/**?auth_key=abdf2123-6783232**
StorageClass	string	媒资存储类型。取值： Standard：标准。 IA：媒资低频。 Archive：媒资归档。 ColdArchive：媒资冷归档。 SourceIA：源文件低频。 SourceArchive：源文件归档。 SourceColdArchive：源文件冷归档。 Changing：媒资存储类型变更中。 SourceChanging：源文件存储类型变更中。	Standard
PlayInfoList	array<object>	音/视频播放信息（流信息）。
PlayInfo	object	音/视频详细信息。
CreationTime	string	创建时间。格式为：yyyy-MM-ddTHH:mm:ssZ（UTC 时间）。	2022-04-18T07:37:15Z
Status	string	媒体流状态，取值： Normal：正常状态，标记的是每种清晰度和格式的一路最新转码完成的流的状态。 Invisible：不可见状态，当每种清晰度和格式有多路重复的转码流时，除了最新的一路流会被标记为正常状态，其他流会被标记为不可见状态。	Normal
Specification	string	音视频转码输出规格。各取值及描述，请参见输出规格：Specification。	H264.LD
NarrowBandType	string	转码类型。取值： 0：普通转码。 1.0：窄带高清 1.0 转码。 2.0：窄带高清 2.0 转码。	0
Height	long	媒体流高度。单位：px。	640
Bitrate	string	媒体流码率。单位：Kbps。	450.878
ModificationTime	string	更新时间。格式为：yyyy-MM-ddTHH:mm:ssZ（UTC 时间）。	2022-04-20T06:32:19Z
WatermarkId	string	当前媒体流关联的水印模板 ID。	dgfn26457856****
Encrypt	long	媒体流是否加密流，取值： 0：否。 1：是。	1
Definition	string	视频流清晰度定义。取值： FD：流畅。 LD：标清。 SD：高清。 HD：超清 OD：原画。 2K：2K。 4K：4K。 SQ：普通音质。 HQ：高音质。 AUTO：自适应码率。	LD
EncryptType	string	媒体流加密类型。取值： AliyunVoDEncryption：阿里云视频加密。 HLSEncryption：HLS 标准加密。说明如果加密类型为 AliyunVoDEncryption，则只能使用阿里云播放器 SDK 才能正常播放。	AliyunVoDEncryption
EncryptMode	string	媒体流加密模式。取值： License：本地解密模式。说明如果加密模式为 License，则只能使用阿里云播放器 SDK 才能正常播放。	License
StreamType	string	媒体流类型。若媒体流为视频则取值：video，若是纯音频则取值：audio。	video
JobId	string	媒体流转码的作业 ID。作为媒体流的唯一标识。	80e9c6580e754a798c3c19c59b16****
Size	long	媒体流大小。单位：Byte。	418112
Width	long	媒体流宽度。单位：px。	360
Fps	string	媒体流帧率。单位：帧/每秒。	25
Duration	string	媒体流长度。单位：秒。	9.0464
PlayURL	string	视频流的播放地址。	https://example.aliyundoc.com/d52ee123f331466aabf6ab32a93d**/a777f9e24e6e47a2a942467d5c38ea37-8ee8e04293c6657fdda282bc422704**.m3u8
Format	string	媒体流格式。若媒体文件为视频则取值： mp4、 m3u8。若是纯音频则取值：mp3。	m3u8
HDRType	string	媒体流 HDR 类型。取值： HDR HDR10 HLG DolbyVision HDRVivid SDR+	HLG
BitDepth	integer	颜色位深。取值为整数。	8
JobType	integer	数字水印类型。取值： 1：溯源水印。 2：版权水印。	2
JobExt	string	版权水印的自定义水印信息。仅当`JobType`为`2`时返回该字段。	CopyrightMarkTest

示例

正常返回示例

JSON格式

{
  "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": "阿里云VOD",
    "MediaType": "video",
    "DanMuURL": "http://example.aliyundoc.com/****?auth_key=abdf2123-6783232****",
    "StorageClass": "Standard"
  },
  "PlayInfoList": {
    "PlayInfo": [
      {
        "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",
        "EncryptMode": "License",
        "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,
        "JobType": 2,
        "JobExt": "CopyrightMarkTest",
        "CodecName": ""
      }
    ]
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2024-12-09	OpenAPI 返回结构发生变更	查看变更详情
2024-10-11	OpenAPI 返回结构发生变更	查看变更详情
2023-10-18	OpenAPI 入参发生变更	查看变更详情
2023-09-05	OpenAPI 返回结构发生变更	查看变更详情
2021-12-23	OpenAPI 返回结构发生变更	查看变更详情
2021-11-16	OpenAPI 返回结构发生变更	查看变更详情

接口错误码

下表列举了本接口特有的错误码。

错误代码	错误信息	HTTP 状态码	说明
Forbidden.IllegalStatus	Status of the video is illegal. Current Status is %s.	403	视频状态无效，当前状态为%s。只有 Normal 状态的视频才能播放。
InvalidVideo.NotFound	The video does not exist.	404	视频不存在。
InvalidVideo.NoneStream	The video has no stream to play for the request parameter ‘Formats : mp4, Definition : LD, StreamType : video’.	404	根据您的筛选条件找不到可以播放的转码输出流，请检查您的转码配置与筛选条件是否匹配。
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	当前仅存在阿里云视频加密的转码输出流，必须使用阿里云播放器进行播放或者设置请求参数 ResultType 值为 Multiple。