首页 视频点播 API参考指南 API目录 音视频播放 GetPlayInfo - 获取音视频播放地址

GetPlayInfo - 获取音视频播放地址

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

接口说明

  • 通过音视频ID来获取音视频的播放地址。通过集成阿里云播放器SDK(适用于URL播放方式)或第三方播放器后,可使用获取到的播放地址用于音视频的播放。
  • 只有状态为正常(Status字段值为Normal)的视频才能正常播放。关于播放地址的播放说明及使用限制等更多信息,请参见音视频播放
  • 当视频播放异常时,您可以调用GetMezzanineInfo接口查询视频源文件信息是否正确。
说明更多关于视频点播API的问题咨询,可搜索钉钉群号2720012141入群咨询专家。

调试

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

调试

授权信息

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

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

请求参数

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

音/视频ID。可通过以下方式获取:

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

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

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

播放地址过期时间。单位:秒。

  • 当OutputType取值为cdn时:

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

    • 只有存储权限为私有,播放地址才会定期失效,否则会永久有效。
    • 最小值:1
    • 最大值:为降低源站安全风险,最大值为2592000(即30天)。
    • 默认值:未设置时,取值为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

    返回参数

    名称类型描述示例值
    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****
    PlayInfoListarray

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

    object

    音/视频详细信息。

    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

    示例

    正常返回示例

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

    错误码

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

    变更历史

    变更时间变更内容概要操作
    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
    阿里云首页 视频点播 相关技术圈