全部產品
Search

搜尋本產品

    ApsaraVideo VOD：UploadMediaByURL

    文件中心

    ApsaraVideo VOD：UploadMediaByURL

    更新時間：Jul 21, 2026

    基於來源檔案 URL，拉取影音媒體檔案進行上傳，支援批次上傳。

    介面說明

    • 請確保在使用該介面前，已充分了解影片點播產品的收費方式和價格。媒資檔案上傳到影片點播中會產生儲存費用，計費詳情，請參見媒資儲存計費。如果您已啟用了儲存傳輸加速，則上傳媒資檔案到影片點播時還將涉及上傳加速費用，計費詳情請參見儲存傳輸加速計費。

    • 本介面支援上傳的媒體檔案格式，請參見媒體格式。

    • 本介面主要適用於檔案沒有儲存在本機伺服器或終端，需要透過公網存取的 URL 位址上傳的情境。

    • 本介面為非同步上傳介面，非即時，不保證時效性，一般提交後會在數小時、甚至數天內完成遷移上傳。如果對時效性要求較高，建議使用上傳 SDK 上傳。

    • 如果設定了回呼，則上傳完成後會收到URL 上傳影片完成的事件通知，可以透過獲取 URL 上傳資訊介面查詢上傳狀態。

    • 上傳任務提交成功後，會在雲端產生非同步執行的任務，相應服務地域下所有使用者提交的 URL 上傳任務進行排隊執行，完成時間受已有任務數量影響；上傳完成後可根據事件通知（訊息回呼）返回的 URL 和影片 ID 等資訊進行關聯。

    • 本介面目前僅支援華東 2（上海）、華北 2（北京）、華南 1（深圳）、新加坡、美國（矽谷）地域。

    • 同一個媒體檔案 URL，每次提交上傳任務都會在點播中產生一個新的媒體資源（即產生新的媒體 ID）。

    • 單一檔案超過 20GB 時，將導致上傳失敗。如您有單一檔案超過 20GB 的上傳需求，請使用上傳 SDK 進行上傳。詳細資訊請參見上傳 SDK 概述。

    調試

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

    調試

    授權資訊

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

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

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

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

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

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

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

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

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    vod:UploadMediaByURL

    create

    *All Resource

    *

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    UploadURLs

    string

    是

    媒體來源檔案 URL。

    • URL 中需要包含副檔名，例如 https://****.mp4 中 mp4 為副檔名。

      • 如果 URL 中不包含副檔名，可以在 UploadMetadatas 中傳入 FileExtension 來指定。

      • 如果 URL 中有副檔名且同時傳入 FileExtension，以傳入的 FileExtension 為準。

      • 指定支援的副檔名，請參見上傳概述。

    說明

    • URL 編碼，多個位址之間以半形逗號（,）分隔，最多支援 20 個，避免存在特殊字元導致無法上傳影片，需要 URL 編碼後再做逗號拼接。

    https://****.mp4
    TemplateGroupId

    string

    否

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

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

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

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

    說明

    • 不設定轉碼範本群組 ID，則按預設的轉碼範本群組進行轉碼；設定了轉碼範本群組 ID 時，會使用該指定的範本群組進行轉碼。

    • 可以在 UploadMetadatas 中進行設定，如果在 UploadMetadatas 中設定了 TemplateGroupId，此處也設定了 TemplateGroupId，則以 UploadMetadatas 中設定的 TemplateGroupId 為準。

    ca3a8f6e4957b65806709586****
    StorageLocation

    string

    否

    媒體檔案儲存位址。

    登入點播主控台，選擇配置管理 > 媒資管理配置 > 儲存管理檢視儲存位址。不指定時會使用預設儲存位址。

    outin-bfefbb90a47c******163e1c7426.oss-cn-shanghai.aliyuncs.com
    UploadMetadatas

    string

    否

    上傳媒體檔案的中繼資料資訊，為 JSON 字串。

    • 與 UploadURLs 裡的 URL 匹配才能生效。

    • JSON 格式：[UploadMetadata, UploadMetadata,…]，需轉為 JSON 字串。

    • 更多資訊，請參見下表 UploadMetadata。

    [{"SourceURL":"https://example.aliyundoc.com/video01.mp4","Title":"urlUploadTest"}]
    UserData

    string

    否

    自訂設定。為 JSON 字串，支援訊息回呼、上傳加速等設定。更多資訊，請參見 UserData 。

    說明

    • 此參數中訊息回呼的使用前提是需要在主控台配置 HTTP 回呼位址和勾選對應的回呼事件類型才能使用，否則回呼設定不生效。主控台配置 HTTP 回呼的操作，請參考回呼設定。

    • 如需使用上傳加速功能，您需要提交工單申請啟用，更多資訊，請參見上傳相關說明。關於如何提交工單，請參見聯絡我們。

    {"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
    AppId

    string

    否

    應用程式 ID。預設取值：app-1000000。更多資訊，請參見多應用。

    app-****
    WorkflowId

    string

    否

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

    說明

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

    e1e243b42548248197d6f74f9****
    SessionId

    string

    否

    自訂去重識別碼，如果傳遞了該參數請求，當偵測到在過去 10 分鐘內曾有過相同識別碼的請求，則會在本次請求時返回錯誤。

    說明

    • 該去重識別碼由您自訂設定，長度最長為 50 個字元，支援大小寫英文字母、數字、短橫線（-）和底線（_），不傳或者帶空字串表示不去重。

    5c62d40299034bbaa4c195da330****
    EnableFirstFrameCover

    boolean

    否

    GenerateThumbnail

    boolean

    否

    UploadMetadata

    名稱類型是否必需描述
    SourceURLString是需要上傳的媒體來源檔案 URL。
    TitleString否媒體標題。長度不超過 128 個位元組。UTF-8 編碼。
    FileSizeString否檔案大小。
    DescriptionString否描述。長度不超過 1024 個位元組。UTF-8 編碼。
    CoverURLString否自訂影片封面 URL 位址。
    CateIdString否分類 ID。可透過登入點播主控台，選擇配置管理 > 媒資管理配置 > 分類管理檢視分類 ID。
    TagsString否標籤。單一標籤不超過 32 位元組，最多不超過 16 個標籤。多個標籤，請使用半形逗號（,）分隔。UTF8 編碼。
    TemplateGroupIdString否轉碼範本群組 ID。會覆蓋外層傳入的 TemplateGroupId。
    WorkflowIdString否工作流程 ID。如果同時傳入了 WorkflowId 和 TemplateGroupId，以 WorkflowId 為準。更多資訊，請參見工作流程。
    FileExtensionString否媒體檔案副檔名，支援的副檔名，請參見上傳概述。
    ReferenceIdString否自訂 ID，僅支援小寫字母、大寫字母、數字、橫線、底線，長度 6-64 位元。使用者維度唯一。
    說明

    • UploadMetadata 中的參數（如 Title、Description、Tags 等）不能包含表情符號。

    • 為確保正常播放，當 TemplateGroupId 設定為「VOD_NO_TRANSCODE」不轉碼的方式上傳影片檔案後，目前僅以下格式的檔案支援不轉碼直接播放：MP4、FLV、MP3、M3U8、WEBM，其他格式僅支援儲存（關注 FileName 的副檔名）。若使用阿里雲播放器，版本須為 3.1.0 或以上。

    • 指定不轉碼的範本群組（TemplateGroupId 設定為「VOD_NO_TRANSCODE」），影片上傳後僅有影片上傳完成的事件通知，沒有單一清晰度轉碼完成的事件通知。

    • 如果設定了回呼，影片上傳完成後，除了上傳和轉碼通知，還有URL 上傳影片完成事件通知。

    • 批次提交時，每一個 SourceURL 有獨立的通知。

    返回參數

    名稱

    類型

    描述

    樣本值

    object

    返回結果。

    RequestId

    string

    請求 ID。

    25818875-5F78-4AF6-D7393642CA58****
    UploadJobs

    array<object>

    上傳任務清單。

    object

    上傳任務詳情。

    SourceURL

    string

    上傳任務對應的來源檔案 URL。

    http://example****.mp4
    JobId

    string

    上傳任務 ID。

    ad90a501b1b94fb72374ad005046****

    樣本

    正常返回樣本

    JSON格式

    {
  "RequestId": "25818875-5F78-4AF6-D7393642CA58****",
  "UploadJobs": [
    {
      "SourceURL": "http://example****.mp4",
      "JobId": "ad90a501b1b94fb72374ad005046****"
    }
  ]
}

    錯誤碼

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

    變更歷史

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