全部產品
Search

搜尋本產品

    ApsaraVideo VOD：UploadStreamByURL

    文件中心

    ApsaraVideo VOD：UploadStreamByURL

    更新時間：Jul 21, 2026

    上傳外部儲存的轉碼流檔案並掛載到對應的隨選視訊媒體資源下。

    介面說明

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

    • 該介面目前僅支援上海和新加坡地域使用。

    • 呼叫本介面上傳外部儲存的轉碼流檔案並掛載到對應的隨選視訊媒體資源下。本介面支援的轉碼流 HDR 類型為 HDR、HDR10、HLG、DolbyVision、HDRVivid 和 SDR+ 類型。

    • 您可以透過取得 URL 上傳資訊介面來查詢上傳狀態，上傳完成後會收到URL 上傳轉碼流完成的事件通知。

    調試

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

    調試

    授權資訊

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

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

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

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

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

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

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

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

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    vod:UploadStreamByURL

    create

    *All Resource

    *

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    StreamURL

    string

    是

    轉碼流檔案 URL。

    如果轉碼流的 URL 需要驗證，需要在 StreamURL 中傳入驗證參數，並確保該 URL 可以透過公網存取。

    說明

    URL 可以透過主控台取得音訊影片的位址；也可以透過 GetPlayInfo 介面呼叫來取得音訊影片位址。

    https://example.com/lesson-01.mp4
    MediaId

    string

    是

    轉碼流對應的隨選視訊媒體資源 ID。

    ca3a8f6e49*****57b65806709586
    Definition

    string

    是

    影片流清晰度。

    取值，詳情請參考：媒體資源參數說明-清晰度。

    HD
    FileExtension

    string

    否

    轉碼流檔案副檔名。

    副檔名請參見概述中的音訊和影片支援的檔案格式。

    當該參數不為空時，會覆蓋 StreamURL 位址中的檔案副檔名。

    重要 若 StreamURL 位址中不含檔案副檔名，該參數必填。

    mp4
    HDRType

    string

    否

    轉碼流 HDR 類型。取值：

    • HDR

    • HDR10

    • HLG

    • DolbyVision

    • HDRVivid

    • SDR+

    說明

    • 大小寫不敏感。

    • 非 HDR 影片該參數為空即可。

    HDR10
    UserData

    string

    否

    使用者自訂參數。詳情參見 UserData 。

    說明

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

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

    string

    否

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

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

    {"AddressMapping":"1","CustomPath":"test/xxx","CustomFileName":"xxx.mp4","isOverwritePath":"0"}

    UploadMetadata

    名稱類型是否必需描述
    AddressMappingString否位址對應規則。取值：1 代表對應轉碼流的 URL，2 代表自訂路徑
    CustomPathString否自訂檔案路徑。長度不超過 1000 個位元組。UTF-8 編碼。
    CustomFileNameString否自訂檔案名稱。長度不超過 1000 個位元組。UTF-8 編碼。
    IsOverwritePathString否自訂檔案路徑存在時是否覆蓋。取值：0 代表不覆蓋，1 代表覆蓋
    說明

    • 當 AddressMapping 取值為 2 時，CustomPath 和 CustomFileName 均不能為空

    • 當 IsOverwritePath 取值為 0 時，如果自訂的檔案路徑已經存在，介面會返回失敗

    返回參數

    名稱

    類型

    描述

    樣本值

    object

    基本資訊。

    RequestId

    string

    請求 ID。

    7AE96389-DF1E-598D-816B-7B40F13B4620
    StreamJobId

    string

    轉碼流 JobId。可以作為 GetURLUploadInfos 介面的請求參數。

    隨選視訊使用 JobId 唯一識別一個轉碼流檔案。詳情請參考：基本資料-PlayInfo 影片播放資訊。

    e304b34fb3d959f92baef97b6496****
    FileURL

    string

    轉碼流 OSS 檔案位址。

    http://outin-31059bcee7810a200163e1c8dba****.oss-cn-shanghai.aliyuncs.com/lesson-01.mp4
    SourceURL

    string

    轉碼流輸入 URL 位址。可以作為 GetURLUploadInfos 介面的請求參數。

    https://example.com/lesson-01.mp4

    樣本

    正常返回樣本

    JSON格式

    {
  "RequestId": "7AE96389-DF1E-598D-816B-7B40F13B4620",
  "StreamJobId": "e304b34fb3d959f92baef97b6496****",
  "FileURL": "http://outin-31059bcee7810a200163e1c8dba****.oss-cn-shanghai.aliyuncs.com/lesson-01.mp4",
  "SourceURL": "https://example.com/lesson-01.mp4"
}

    錯誤碼

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

    變更歷史

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