全部產品
Search

搜尋本產品

    ：GetPlayInfo - 擷取音視頻播放地址

    文件中心

    ：GetPlayInfo - 擷取音視頻播放地址

    更新時間：Dec 09, 2025

    調用此介面並提供音視頻ID即可擷取播放地址，隨後可使用阿里雲播放器或第三方播放器（如系統原生、開源或自研播放器）播放音視頻內容。

    介面說明

    • 請確保在使用該介面前，已充分瞭解ApsaraVideo for VOD產品的收費方式和價格。從點播的播放地址直接下載或播放視頻將產生下行流量費用，未配置加速網域名稱時請參見儲存流出流量計費；已配置加速網域名稱時請參見加速服務計費。如果您已開通了儲存傳輸加速，則從點播的播放地址直接下載或播放視頻還將涉及下載加速費用，計費詳情請參見儲存傳輸加速計費。

    • 只有狀態為正常（Status 欄位值為 Normal）的視頻才能正常播放。關於播放地址的播放說明及使用限制等更多資訊，請參見音視頻播放。

    • 當媒資儲存類型為非標準儲存時，需要對 PlayConfig 參數的 StorageClass 欄位進行相應設定，詳情請參見 PlayConfig 。

    • 當視頻播放異常時，您可以調用 GetMezzanineInfo 介面查詢視頻源檔案資訊是否正確。

    調試

    您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

    調試

    授權資訊

    下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

    • 操作：是指具體的許可權點。

    • 存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。

    • 資源類型：是指操作中支援授權的資源類型。具體說明如下：

      • 對於必選的資源類型，用前面加 * 表示。

      • 對於不支援資源級授權的操作，用全部資源表示。

    • 條件關鍵字：是指雲產品自身定義的條件關鍵字。

    • 關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    vod:GetPlayInfo

    get

    *全部資源

    *

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    VideoId

    string

    否

    音/視頻 ID，僅支援傳入單個音/視頻 ID。可通過以下方式擷取：

    • 通過控制台上傳的音/視頻，可登入ApsaraVideo for VOD控制台，選擇媒資庫 > 音/視頻查看音/視頻 ID。

    • 通過 CreateUploadVideo 介面上傳音/視頻時，音/視頻 ID 為返回參數 VideoId 的值。

    • 音/視頻上傳後，可通過 SearchMedia 介面查詢音/視頻 ID，為請求後返回參數 VideoId 的值。

    93ab850b4f654b6e91d24d81d44****
    Formats

    string

    否

    媒體流格式。多個格式之間使用半形逗號（,）分隔。取值：

    • mp4

    • m3u8

    • mp3

    • flv

    • mpd

    說明

    • 預設擷取所有格式的流。

    • mpd 格式僅當轉碼模板中配置了dash封裝格式時才會輸出。更多詳情，請參見Container：封裝格式。

    mp4,m3u8
    AuthTimeout

    integer

    否

    設定播放地址的有效時間。單位：秒。

    • 當 OutputType 取值為 cdn 時：

      • 只有開啟了 URL 鑒權，播放地址才會定期失效，否則會永久有效。URL 鑒權的開啟及配置方法，請參見 URL 鑒權。

      • 最小值：1。

      • 最大值：無限制。

      • 預設值：未設定時，取值為 URL 鑒權中設定的預設有效時間長度。

    • 當 OutputType 取值為 oss 時：

      • 只有儲存許可權為私人，播放地址才會定期失效，否則會永久有效。

      • 最小值：1。

      • 最大值：為降低來源站點安全風險，當音視頻儲存在點播系統 Bucket 上時，最大值為 604800（即 7 天），當音視頻儲存在 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不設定時，介面預設使用點播配置的預設網域名稱；如果沒有設定預設網域名稱，則會根據網域名稱的修改時間倒序查詢，使用最新修改過的網域名稱作為播放網域名稱。為防止返回的不是想要的網域名稱，建議設定預設播放網域名稱（可登入ApsaraVideo for VOD控制台，選擇組態管理 > 媒資管理配置 > 儲存管理 > 管理 > 回源到此儲存地址的網域名稱設定預設播放網域名稱）。

    • 當 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
    ReferenceId

    string

    否

    自訂 ID，僅支援小寫字母、大寫字母、數字、橫線、底線，長度 6-64 位元。使用者維度唯一。

    123-123

    返回參數

    名稱

    類型

    描述

    樣本值

    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 回調及視頻截圖完成事件。

    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

    object

    PlayInfo

    array<object>

    音/視頻播放資訊（流資訊）。

    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

    integer

    媒體流高度。單位：px。

    640
    Bitrate

    string

    媒體流碼率。單位：Kbps。

    說明

    受 M3U8 動態分區特性影響，其碼率計算可能存在偏差。

    450.878
    ModificationTime

    string

    更新時間。格式為：yyyy-MM-ddTHH:mm:ssZ（UTC 時間）。

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

    string

    當前媒體流關聯的浮水印模板 ID。

    dgfn26457856****
    Encrypt

    integer

    媒體流是否加密流，取值：

    • 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

    integer

    媒體流大小。單位：Byte。

    說明

    受 M3U8 動態分區特性影響，其媒體流大小計算可能存在偏差。

    418112
    Width

    integer

    媒體流寬度。單位：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
    CodecName

    string

    編碼類別型。取值：

    • H264

    • H265

    H264

    樣本

    正常返回樣本

    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": "H264"
      }
    ]
  }
}

    錯誤碼

    訪問錯誤中心查看更多錯誤碼。

    變更歷史

    更多資訊，參考變更詳情。