All Products
Search

This Product

    ApsaraVideo VOD:UploadStreamByURL

    Document Center

    ApsaraVideo VOD:UploadStreamByURL

    Last Updated:Jul 21, 2026

    Uploads a transcoded stream file from external storage and mounts it to the corresponding ApsaraVideo VOD media asset.

    Operation description

    • Before using this operation, make sure that you fully understand the billing methods and pricing of ApsaraVideo VOD. Uploading media files to ApsaraVideo VOD incurs storage fees. For more information, see Media asset storage billing. If you have enabled storage transmission acceleration, upload acceleration fees also apply. For more information, see Storage transmission acceleration billing.

    • This operation is currently supported only in the Shanghai and Singapore regions.

    • Call this operation to upload a transcoded stream file from external storage and mount it to the corresponding ApsaraVideo VOD media asset. The supported HDR types for transcoded streams are HDR, HDR10, HLG, DolbyVision, HDRVivid, and SDR+.

    • You can call the GetURLUploadInfos operation to query the upload status. After the upload is complete, you will receive the URL upload transcoded stream complete event notification.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    vod:UploadStreamByURL

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    StreamURL

    string

    Yes

    The URL of the transcoded stream file.

    If the URL of the transcoded stream requires authentication, include the authentication parameters in StreamURL and make sure the URL is accessible through public network access.

    Note

    You can obtain the audio or video URL from the console or by invoking the GetPlayInfo operation.

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

    string

    Yes

    The ID of the ApsaraVideo VOD media asset that corresponds to the transcoded stream.

    ca3a8f6e49*****57b65806709586
    Definition

    string

    Yes

    The definition of the video stream.

    For valid values of this parameter, see Media asset parameter description - Definition.

    HD
    FileExtension

    string

    No

    The file name extension of the transcoded stream file.

    For supported audio and video file formats, see Overview.

    If this parameter is not empty, it overwrites the file name extension in the StreamURL.

    Important This parameter is required if the StreamURL does not contain a file name extension.

    mp4
    HDRType

    string

    No

    The HDR type of the transcoded stream. Valid values:

    • HDR

    • HDR10

    • HLG

    • DolbyVision

    • HDRVivid

    • SDR+

    Note

    • Case-insensitive.

    • Leave this parameter empty for non-HDR videos.

    HDR10
    UserData

    string

    No

    The custom parameter. For more information, see UserData.

    Note

    To use the message callback in this parameter, configure the HTTP callback URL and select the corresponding callback event types in the console. Otherwise, the callback settings do not take effect. For information about how to configure HTTP callbacks in the console, see Callback settings.

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

    string

    No

    The metadata of the media file to upload. The value is a JSON string.

    • For more information, see the UploadMetadata table below.

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

    UploadMetadata

    NameTypeRequiredDescription
    AddressMappingStringNoThe address mapping rule. Valid values: 1: maps the URL of the transcoded stream. 2: uses a custom path.
    CustomPathStringNoThe custom file path. Maximum length: 1000 bytes. UTF-8 encoded.
    CustomFileNameStringNoThe custom file name. Maximum length: 1000 bytes. UTF-8 encoded.
    IsOverwritePathStringNoSpecifies whether to overwrite the file if the custom file path already exists. Valid values: 0: does not overwrite. 1: overwrites.
    Note

    • When AddressMapping is set to 2, both CustomPath and CustomFileName are required.

    • When IsOverwritePath is set to 0, the operation returns a failure if the custom file path already exists.

    Response elements

    Element

    Type

    Description

    Example

    object

    The basic information.

    RequestId

    string

    The request ID.

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

    string

    The job ID of the transcoded stream. This value can be used as a request parameter of the GetURLUploadInfos operation.

    ApsaraVideo VOD uses the job ID to uniquely identify a transcoded stream file. For more information, see Basic data types - PlayInfo.

    e304b34fb3d959f92baef97b6496****
    FileURL

    string

    The OSS file URL of the transcoded stream.

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

    string

    The input URL of the transcoded stream. This value can be used as a request parameter of the GetURLUploadInfos operation.

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

    Examples

    Success response

    JSON format

    {
  "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"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.