全部產品
Search

搜尋本產品

    Intelligent Media Services：UploadMediaByURL

    文件中心

    Intelligent Media Services：UploadMediaByURL

    更新時間：Aug 06, 2026

    呼叫 UploadMediaByURL 基於來源檔案 URL，拉取影音媒體檔案進行上傳，支援批次上傳。本介面主要適用於檔案未儲存在本地伺服器或終端，需要透過公網存取的 URL 位址上傳的場景。

    介面說明

    介面說明

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

    • 上傳任務提交成功後，會在雲端產生非同步執行的任務，進行排隊執行；上傳完成後可根據事件通知（訊息回呼）返回的 URL 和影片 ID 等資訊進行關聯。

    使用限制

    • 本介面僅支援上傳至 VOD 隨選視訊儲存，不支援上傳至使用者自有 OSS 儲存。使用自有 OSS 儲存的使用者，可以先將檔案拉取到本地，透過 OSS SDK 上傳檔案至 OSS，然後再呼叫 RegisterMediaInfo 介面將 OSS 檔案註冊至媒體資源庫。

    • 本介面目前僅支援華東 2（上海）、華北 2（北京）、華南 1（深圳）地域。

    • 本介面僅支援上傳影音檔案。

    調試

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

    調試

    授權資訊

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

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

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

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

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

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

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

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

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    ice:UploadMediaByURL

    create

    *全部資源。

    *

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    UploadURLs

    string

    否

    媒體來源檔案 URL。

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

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

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

    • URL 編碼，多個位址之間以半形逗號（,）分隔，最多支援 20 個。

    • 避免存在特殊字元導致無法上傳影片，需要 URL 編碼後再做逗號拼接。

    https://diffurl.mp4
    AppId

    string

    否

    應用程式 ID。

    app-1000000
    UserData

    string

    否

    自訂設定。為 JSON 字串，支援訊息回呼等設定。

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

    string

    否

    目標儲存位址。

    • StorageType 取值：僅支援 oss。

    • StorageLocation 僅支援 VOD 隨選視訊儲存，不支援使用者自有 OSS 儲存。

    {"StorageType":"oss","StorageLocation":"outin-***.oss-cn-shanghai.aliyuncs.com"}
    MediaMetaData

    string

    否

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

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

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

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

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

    string

    否

    Type = video || audio 有上傳後處理動作。

    ProcessType 取值：Workflow。

    {"ProcessType": "Workflow","ProcessID":"b72a06c6beeb4dcdb898feef067b1***"}
    EntityId

    string

    否

    實體 ID。可呼叫 CreateEntity 介面建立實體，自訂動態中繼資料結構。

    d67281da3c8743b8823ad12976187***

    UploadMetadata

    名稱類型是否必需描述
    SourceURLString是需要上傳的媒體來源檔案 URL。
    TitleString是媒體標題。長度不超過 128 個位元組。UTF-8 編碼。
    FileSizeString否檔案大小。
    DescriptionString否描述。長度不超過 1024 個位元組。UTF-8 編碼。
    CoverURLString否自訂影片封面 URL 位址。
    CateIdString否分類 ID。
    TagsString否標籤。單個標籤不超過 32 位元組，最多不超過 16 個標籤。多個標籤，請使用半形逗號（,）分隔。UTF8 編碼。
    WorkflowIdString否工作流程 ID。
    FileExtensionString否媒體檔案副檔名。
    DynamicMetaDataString否動態中繼資料，例："{"Uploader": "xxx"}"。
    EntityIdString否實體 Id。
    說明

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

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

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

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

    返回參數

    名稱

    類型

    描述

    樣本值

    object

    返回結果。

    RequestId

    string

    請求 ID。

    ****83B7-7F87-4792-BFE9-63CD2137****
    UploadJobs

    array<object>

    多個 Job 資訊。

    object

    上傳任務詳情。

    JobId

    string

    上傳任務 ID。

    20ce1e05dba64576b96e9683879f0***
    SourceURL

    string

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

    http://example****.mp4

    MediaId

    string

    媒體資源 ID。

    f476988629f54a7b8a4ba90d1a6c7***

    樣本

    正常返回樣本

    JSON格式

    {
  "RequestId": "****83B7-7F87-4792-BFE9-63CD2137****",
  "UploadJobs": [
    {
      "JobId": "20ce1e05dba64576b96e9683879f0***",
      "SourceURL": "http://example****.mp4\n",
      "MediaId": "f476988629f54a7b8a4ba90d1a6c7***"
    }
  ]
}

    錯誤碼

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

    變更歷史

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