全部產品
Search

搜尋本產品

    ApsaraVideo VOD：RegisterMedia

    文件中心

    ApsaraVideo VOD：RegisterMedia

    更新時間：Jul 21, 2026

    進行媒體資源註冊，接入點播服務的 OSS 自有 Bucket 上的存量媒體資源檔案，需要進行媒體資源註冊以產生點播所需的關聯資料後，才能正常使用點播提供的轉碼、截圖等功能。

    介面說明

    • 針對已接入點播服務的 OSS bucket，已儲存在 OSS bucket 上的影音媒體檔案，需要透過註冊媒體資源介面產生點播所需的關聯資料後，才能在點播服務中對這些媒體檔案透過媒體 ID 發起轉碼、截圖和 AI 處理等。

    • 一次最多可註冊 10 個 OSS 媒體檔案，且一次提交的媒體檔案對應的儲存地址需要一致。

    • 在點播中上傳的媒體檔案，如未指定轉碼範本群組 ID，則會按照預設範本群組進行轉碼處理；與之不同的是，註冊媒體資源後，如未指定轉碼範本群組 ID，則不會自動觸發轉碼；如指定了轉碼範本群組 ID，則會按照指定的範本群組進行轉碼處理。

    • 重複註冊的媒體檔案，只返回與其關聯的唯一媒體 ID，不做其他處理。

    • 請確保您要註冊的媒體資源檔案含有合法的副檔名，否則會註冊失敗。

    調試

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

    調試

    授權資訊

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

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

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

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

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

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

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

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

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    vod:RegisterMedia

    create

    *All Resource

    *

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    RegisterMetadatas

    string

    是

    註冊媒體資源中繼資料。為 JSON 字串，一次最多支援設定 10 個媒體資源中繼資料。參數結構的更多資訊，請參見下表 RegisterMetadata。

    [{"FileURL":"https://****.oss-cn-shanghai.aliyuncs.com/video/test/video123.m3u8","Title":"VideoName"}]
    TemplateGroupId

    string

    否

    轉碼範本群組 ID。可透過以下方式獲取：

    • 登入點播控制台，選擇配置管理 > 媒體處理配置 > 轉碼範本群組檢視轉碼範本群組 ID。

    • 透過建立轉碼範本群組介面建立轉碼範本群組時，轉碼範本群組 ID 為返回參數 TranscodeTemplateGroupId 的值。

    • 透過查詢轉碼配置列表介面查詢轉碼範本群組時，為請求後返回參數 TranscodeTemplateGroupId 的值。

    說明

    • 如果不需要轉碼，請指定為 VOD_NO_TRANSCODE（不轉碼範本群組），否則影片狀態會為上傳完成，從而無法使用播放服務播放影音。如果需要轉碼，則指定對應轉碼範本群組 ID。

    • 如果同時傳遞了 WorkflowId 和 TemplateGroupId，以 WorkflowId 為準。使用說明，請參見工作流。

    • 該參數任務為非同步任務，提交後任務尚未完成，任務將進入後台排隊非同步執行。

    ca3a8f6e49c87b65806709586****
    UserData

    string

    否

    自訂設定。為 JSON 字串，支援訊息回呼等設定。參數詳情，請參見 UserData 。

    說明

    本介面不支援回呼，即便此參數中設定了訊息回呼，在媒體資源註冊完成後也不會產生回呼訊息。當後續對註冊完成的媒體資源發起轉碼、截圖等媒體處理時，若在發起轉碼、截圖時單獨設定了 UserData 中的訊息回呼，則優先使用那個回呼地址；未設定，則使用此處註冊媒體資源時 UserData 中設定的回呼地址。

    {"Extend":{"localId":"****","test":"www"}}
    WorkflowId

    string

    否

    工作流 ID。可登入點播控制台，選擇配置管理 > 媒體處理配置 > 工作流管理檢視工作流 ID。

    說明

    • 如果同時傳遞了 WorkflowId 和 TemplateGroupId，以 WorkflowId 為準。使用說明，請參見工作流。

    • 該參數任務為非同步任務，提交後任務尚未完成，任務將進入後台排隊非同步執行。

    637adc2b7ba51a83d841606f8****
    EnableFirstFrameCover

    boolean

    否

    GenerateThumbnail

    boolean

    否

    RegisterMetadata

    指定要註冊的媒體資源中繼資料。

    名稱類型是否必選描述
    FileURLString是來源檔案地址。可透過獲取來源檔案資訊介面獲取。
    長度不超過 1024 個位元組，檔案名稱需要保證全域唯一。新增相同檔案名稱時，則關聯唯一媒體 ID。結構為 OSS bucket 的公網存取地址 + ObjectName（檔案名稱）。

    TitleString是標題。長度不超過 128 個位元組。UTF8 編碼。
    DescriptionString否描述。長度不超過 1024 個位元組。UTF8 編碼。
    TagsString否標籤。單個標籤不超過 32 個位元組，最多不超過 16 個標籤，多個標籤之間用半形逗號 (,) 分隔。UTF8 編碼。
    CoverURLString否封面 URL。長度不超過 1024 個位元組。
    CateIdLong否分類 ID。可透過以下方式獲取：
    登入點播控制台，選擇配置管理 > 媒體資源管理配置 > 分類管理檢視分類 ID。
    透過建立分類介面建立分類時，分類 ID 為返回參數 CateId 的值。
    透過獲取分類及子分類介面查詢分類時，為請求後返回參數 CateId 的值。







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

    返回參數

    名稱

    類型

    描述

    樣本值

    object

    返回結果。

    RequestId

    string

    請求 ID。

    14F43C5C-8033-448B-AD04F64E5098****
    FailedFileURLs

    array

    註冊失敗的檔案地址列表。

    string

    註冊失敗的檔案地址列表。

    ["http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"]
    RegisteredMediaList

    array<object>

    本次註冊成功的 Media 列表，包括新增註冊和已註冊成功過的檔案。

    object

    註冊詳情。

    NewRegister

    boolean

    新註冊或重複註冊。

    • true：表示新註冊。

    • false：表示重複註冊。

    false
    FileURL

    string

    OSS 檔案地址。

    http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4
    MediaId

    string

    點播媒體 ID。當註冊的媒體檔案為影音時，對應點播的 VideoId。

    d97af32828084d1896683b1aa38****

    樣本

    正常返回樣本

    JSON格式

    {
  "RequestId": "14F43C5C-8033-448B-AD04F64E5098****",
  "FailedFileURLs": [
    "[\"http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4\"]"
  ],
  "RegisteredMediaList": [
    {
      "NewRegister": false,
      "FileURL": "http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4",
      "MediaId": "d97af32828084d1896683b1aa38****"
    }
  ]
}

    錯誤碼

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

    變更歷史

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