文档

GetPlayInfo - 获取音视频播放地址

通过音视频ID直接获取媒体文件(支持视频和音频)的播放地址。

接口说明

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

调试

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

授权信息

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

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

请求参数

名称类型必填描述示例值
VideoIdstring

音/视频 ID,仅支持传入单个音/视频 ID。可通过以下方式获取:

  • 通过控制台上传的音/视频,可登录点播控制台,选择媒资库 > 音/视频查看音/视频 ID。
  • 通过 CreateUploadVideo 接口上传音/视频时,音/视频 ID 为返回参数 VideoId 的值。
  • 音/视频上传后,可通过 SearchMedia 接口查询音/视频 ID,为请求后返回参数 VideoId 的值。
93ab850b4f654b6e91d24d81d44****
Formatsstring

媒体流格式。多个格式之间使用半角逗号(,)分隔。支持格式:

  • mp4
  • m3u8
  • mp3
  • mpd
说明 默认获取所有格式的流。MPD 格式仅当转码模板中配置了 mpd 封装格式时才会输出。更多详情,请参见转码模板配置-Container
mp4,m3u8
AuthTimeoutlong

设置播放地址的有效时间。单位:秒。

  • 当 OutputType 取值为 cdn 时:

    • 只有开启了 URL 鉴权,播放地址才会定期失效,否则会永久有效。URL 鉴权的开启及配置方法,请参见 URL 鉴权
    • 最小值:1
    • 最大值:无限制。
    • 默认值:未设置时,取值为 URL 鉴权中设置的默认有效时长。
  • 当 OutputType 取值为 oss 时:

    • 只有存储权限为私有,播放地址才会定期失效,否则会永久有效。
    • 最小值:1
    • 最大值:为降低源站安全风险,当音视频存储在点播系统 Bucket 上时,最大值为 2592000(即 30 天),当音视频存储在 OSS 自有 Bucket 上时,最大值为 129600(即 36 小时)。如果此处设置的最大值不能满足您的需求,您可以设置 OutputType 为 cdn,通过设置 URL 鉴权来设置更长的有效期。
    • 默认值:未设置时,取值为 3600
1800
OutputTypestring

输出地址类型。取值:

  • oss:回源地址。
  • cdn(默认):加速地址。
cdn
StreamTypestring

媒体流类型。多个用半角逗号(,)分隔。支持类型:

  • video:视频。
  • audio:音频。

默认获取所有类型的流。

video
ReAuthInfostring

CDN 二次鉴权参数。为 JSON 字符串。当开启了 CDN 二次鉴权功能时,可通过该参数设置鉴权 URL 的 uid 和 rand,请参见 URL 鉴权

{"uid":"12345","rand":"abckljd"}
Definitionstring

视频流清晰度。多个用半角逗号(,)分隔。取值:

  • FD:流畅。
  • LD:标清。
  • SD:高清。
  • HD:超清
  • OD:原画。
  • 2K:2K。
  • 4K:4K。
  • SQ:普通音质。
  • HQ:高音质。
  • AUTO:自适应码率。
说明 默认获取所有清晰度的流。AUTO 格式仅当转码模板中配置了转码打包时才会有该清晰度输出,请参见转码模板配置-PackageSetting
LD
ResultTypestring

返回数据类型。取值:

  • Single(默认):每种清晰度和格式只返回一路最新转码完成的流。
  • Multiple:每种清晰度和格式返回所有转码完成的流。
Single
PlayConfigstring

播放自定义设置。为 JSON 字符串,支持指定域名播放设置。参数构造详情,请参见 PlayConfig

说明
  • PlayConfig 不设置或者其中PlayDomain不设置时,接口默认使用点播配置的默认域名;如果没有设置默认域名,则会根据域名的修改时间倒叙查询,使用最新修改过的域名作为播放域名。为防止返回的不是想要的域名,建议设置默认播放域名(可登录点播控制台,选择配置管理 > 媒资管理配置 > 存储管理 > 管理 > 回源到此存储地址的域名设置默认播放域名)。
  • 当 PlayConfig 中的EncryptType参数设置为AliyunVoDEncryption时,为了保障您的视频安全,默认不返回私有加密流播放地址,若需要返回私有加密流播放地址,需要同时设置ResultType参数为Multiple
  • {"PlayDomain":"vod.test_domain","XForwardedFor":"yqCD7Fp1uqChoVj/sl/p5Q==","PreviewTime":"20","MtsHlsUriToken":"yqCD7Fp1uqChoVjslp5Q"}
    AdditionTypestring

    获取弹幕蒙版数据 URL 地址,取值:danmu

    说明 只有当 outputType 取值为 cdn 时才会生效。
    danmu
    Tracestring

    用户自定义的数字水印信息。

    • DigitalWatermarkType取值为TraceMark时,通过传入本参数,可以为视频设置溯源水印的水印信息,并返回包含水印信息的视频流。仅支持传入英文字母、数字及中文字符,最多支持 1024 个字符。
    • DigitalWatermarkType取值为CopyrightMark时,Trace对应创建水印模板时所设置的水印文字。通过传入本参数,可以查询并返回指定水印文字的视频流。
    test mark
    DigitalWatermarkTypestring

    数字水印类型。取值:

    • TraceMark:溯源水印。
    • CopyrightMark:版权水印。
    TraceMark

    返回参数

    名称类型描述示例值
    object

    返回结果。

    RequestIdstring

    请求 ID。

    F552E596-967D-5500-842F-17E6364****
    VideoBaseobject

    音/视频基本信息。

    CreationTimestring

    音/视频创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

    2017-06-26T06:38:48Z
    Statusstring

    音/视频状态。具体取值范围及描述,请参见视频状态 Status 的取值列表

    Normal
    VideoIdstring

    音/视频 ID。

    93ab850b4f654b6e91d24d81d44****
    CoverURLstring

    音/视频封面地址。

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

    音/视频时长。单位:秒。

    3.1667
    Titlestring

    音/视频标题。

    阿里云VOD
    MediaTypestring

    媒体文件类型,取值:

    • video:视频。
    • audio:纯音频。
    video
    DanMuURLstring

    弹幕蒙版数据的地址。

    http://example.aliyundoc.com/****?auth_key=abdf2123-6783232****
    StorageClassstring

    媒资存储类型。取值:

    • Standard:标准。
    • IA:媒资低频。
    • Archive:媒资归档。
    • ColdArchive:媒资冷归档。
    • SourceIA:源文件低频。
    • SourceArchive:源文件归档。
    • SourceColdArchive:源文件冷归档。
    • Changing:媒资存储类型变更中。
    • SourceChanging:源文件存储类型变更中。
    Standard
    PlayInfoListobject []

    音/视频播放信息(流信息)。

    CreationTimestring

    创建时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

    2022-04-18T07:37:15Z
    Statusstring

    媒体流状态,取值:

    • Normal:正常状态,标记的是每种清晰度和格式的一路最新转码完成的流的状态。
    • Invisible:不可见状态,当每种清晰度和格式有多路重复的转码流时,除了最新的一路流会被标记为正常状态,其他流会被标记为不可见状态。
    Normal
    Specificationstring

    音视频转码输出规格。取值范围,请参见输出规格

    H264.LD
    NarrowBandTypestring

    窄带高清类型。取值:

    • 0:普通。
    • 1.0:窄带高清 1.0。
    • 2.0:窄带高清 2.0。

    仅当配置了窄带高清 1.0 内置转码模板的清晰度时才会生效。更多详情,请参见转码模板配置-Definition

    0
    Heightlong

    媒体流高度。单位:px。

    640
    Bitratestring

    媒体流码率。单位:Kbps。

    450.878
    ModificationTimestring

    更新时间。格式为:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

    2022-04-20T06:32:19Z
    WatermarkIdstring

    当前媒体流关联的水印 ID。

    dgfn26457856****
    Encryptlong

    媒体流是否加密流,取值:

    • 0:否。
    • 1:是。
    1
    Definitionstring

    视频流清晰度定义。取值:

    • FD:流畅。
    • LD:标清。
    • SD:高清。
    • HD:超清
    • OD:原画。
    • 2K:2K。
    • 4K:4K。
    • SQ:普通音质。
    • HQ:高音质。
    • AUTO:自适应码率。
    LD
    EncryptTypestring

    媒体流加密类型。取值:

    • AliyunVoDEncryption:阿里云视频加密。
    • HLSEncryption:HLS 标准加密。
    说明 如果加密类型为 AliyunVoDEncryption,则只能使用阿里云播放器 SDK 才能正常播放。
    AliyunVoDEncryption
    StreamTypestring

    媒体流类型。 若媒体流为视频则取值:video,若是纯音频则取值:audio

    video
    JobIdstring

    媒体流转码的作业 ID。作为媒体流的唯一标识。

    80e9c6580e754a798c3c19c59b16****
    Sizelong

    媒体流大小。单位:Byte。

    418112
    Widthlong

    媒体流宽度。单位:px。

    360
    Fpsstring

    媒体流帧率。单位:帧/每秒。

    25
    Durationstring

    媒体流长度。单位:秒。

    9.0464
    PlayURLstring

    视频流的播放地址。

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

    媒体流格式。

    • 若媒体文件为视频则取值: mp4m3u8
    • 若是纯音频则取值:mp3
    m3u8
    HDRTypestring

    媒体流 HDR 类型。取值:

    • HDR
    • HDR10
    • HLG
    • DolbyVision
    • HDRVivid
    • SDR+
    HLG
    BitDepthinteger

    颜色位深。取值为整数。

    8
    JobTypeinteger

    数字水印类型。取值:

    • 1:溯源水印。
    • 2:版权水印。
    2
    JobExtstring

    版权水印的自定义水印信息。仅当JobType2时返回该字段。

    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",
            "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"
          }
        ]
      }
    }

    错误码

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

    变更历史

    变更时间变更内容概要操作
    2023-10-18OpenAPI 入参发生变更看变更集
    变更项变更内容
    入参OpenAPI 入参发生变更
      新增入参:Trace
      新增入参:DigitalWatermarkType
    2023-09-05OpenAPI 返回结构发生变更看变更集
    变更项变更内容
    出参OpenAPI 返回结构发生变更
    2021-12-23OpenAPI 返回结构发生变更看变更集
    变更项变更内容
    出参OpenAPI 返回结构发生变更
    2021-11-16OpenAPI 返回结构发生变更看变更集
    变更项变更内容
    出参OpenAPI 返回结构发生变更

    接口错误码

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

    错误代码错误信息HTTP 状态码说明
    Forbidden.IllegalStatusStatus of the video is illegal. Current Status is %s.403视频状态无效,当前状态为%s。只有 Normal 状态的视频才能播放。
    InvalidVideo.NotFoundThe video does not exist.404视频不存在。
    InvalidVideo.NoneStreamThe video has no stream to play for the request parameter ‘Formats : mp4, Definition : LD, StreamType : video’.404根据您的筛选条件找不到可以播放的转码输出流,请检查您的转码配置与筛选条件是否匹配。
    Forbidden.AliyunVoDEncryptionCurrently only the AliyunVoDEncryption stream exists, you must use the Aliyun player to play or set the value of ResultType to Multiple.403当前仅存在阿里云视频加密的转码输出流,必须使用阿里云播放器进行播放或者设置请求参数 ResultType 值为 Multiple
    • 本页导读 (1)
    文档反馈