All Products
Search

This Product

    ApsaraVideo VOD:CreateUploadAttachedMedia

    Document Center

    ApsaraVideo VOD:CreateUploadAttachedMedia

    Last Updated:Jul 21, 2026

    The upload URL and credential are provided by ApsaraVideo VOD to address authorization and security concerns, prevent malicious uploads, and enable automatic creation of a media asset ID (MediaId) for management and processing. For auxiliary media assets such as watermarks and subtitles, invoke this operation to obtain the upload credential and create the corresponding media asset information.

    Operation description

    • Before using this operation, make sure that you 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 transfer acceleration, uploading media files to ApsaraVideo VOD also incurs upload acceleration fees. For more information, see Storage transfer acceleration billing.

    • This operation only obtains the upload URL and credential and creates basic media asset information. It does not upload files. For a complete example of uploading files by using the API, see Upload media files by using the ApsaraVideo VOD API.

    • If the upload credential expires (valid for 3000 seconds), call this operation again to obtain a new upload URL and credential.

    • You can configure callbacks to receive event notifications for auxiliary media asset upload complete to determine whether the upload is successful.

    • Obtaining the upload URL and credential is a core fundamental of ApsaraVideo VOD and a required step for every upload operation. ApsaraVideo VOD provides various upload methods, each with different requirements for obtaining the upload URL and credential. For more information, see the instructions in Upload URLs and credentials.

    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:CreateUploadAttachedMedia

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    Title

    string

    No

    The title of the auxiliary media asset. Rules:

    • The title can be up to 128 bytes in length.

    • The title must be encoded in UTF-8.

    Test
    BusinessType

    string

    Yes

    The type of the auxiliary media asset. Valid values:

    • watermark: watermark.

    • subtitle: subtitle.

    • material: material.

    watermark
    MediaExt

    string

    No

    The file name extension of the auxiliary media asset source file to be uploaded. Valid values:

    • Watermark: png, gif, apng, mov.

    • Subtitle: srt, ass, stl, ttml, vtt.

    • Material: jpg, gif, png, mp4, mat, zip, apk.

    Valid values:

    • ass :

      ass

    • jpg :

      jpg

    • zip :

      zip

    • mat :

      mat

    • gif :

      gif

    • apng :

      apng

    • png :

      png

    • ttml :

      ttml

    • stl :

      stl

    • mp4 :

      mp4

    • srt :

      srt

    • mov :

      mov

    • vtt :

      vtt

    • apk :

      apk

    png
    FileName

    string

    No

    The source file address of the auxiliary media asset to be uploaded.

    Note

    The file name extension is optional. If a file name extension is specified here and is different from the extension specified in MediaExt, the value of MediaExt takes precedence.

    D:\test.png
    FileSize

    string

    No

    The file size. Unit: bytes.

    123
    Tags

    string

    No

    The tags. Rules:

    • A maximum of 16 tags are supported.

    • Separate multiple tags with commas (,).

    • Each tag can be up to 32 characters or Chinese characters in length.

    • The tags must be encoded in UTF-8.

    tag1,tag2
    StorageLocation

    string

    No

    The storage address. You can obtain the storage address by using the following method:

    Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Management Configuration > Storage Management to view the storage address.

    Note

    If you do not specify this parameter, the auxiliary media asset is uploaded to the default storage address. If you specify this parameter, the auxiliary media asset is uploaded to the specified storage address.

    out-****.oss-cn-shanghai.aliyuncs.com
    Description

    string

    No

    The description of the media asset. Rules:

    • The description can be up to 1024 bytes in length.

    • The description must be encoded in UTF-8.

    uploadTest
    UserData

    string

    No

    The custom settings, which is a JSON string. The settings support message callbacks, upload acceleration, and other configurations. For more information, see UserData.

    Note

    • To use message callbacks in this parameter, you must configure an 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.

    • To use the upload acceleration feature, submit a ticket to activate it. For more information, see Upload instructions. For information about how to submit a ticket, see Contact us.

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

    string

    No

    The category IDs. Separate multiple IDs with commas (,). A maximum of 5 IDs are supported. You can obtain category IDs by using the following methods:

    • Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Management Configuration > Category Management to view category IDs.

    • The category ID is returned when you call the AddCategory operation to create a category.

    • The category ID is returned when you call the GetCategories operation to query categories.

    1298****,0813****
    AppId

    string

    No

    The application ID. Default value: app-1000000. If you have activated the multi-application service, specify the application ID to upload the auxiliary media asset to the specified application. For more information, see Multi-application.

    app-****

    Response elements

    Element

    Type

    Description

    Example

    object

    The response parameters.

    FileURL

    string

    The OSS URL of the auxiliary media asset file (without authentication).

    When you add an image watermark template, this URL can be used as the request parameter FileUrl of the AddWatermark operation.

    https://****.oss-cn-shanghai.aliyuncs.com/watermark/****.mov
    RequestId

    string

    The request ID.

    73254DE5-F260-4720-D06856B63C01****
    UploadAddress

    string

    The upload URL.

    Note

    The upload URL returned by the operation is a Base64-encoded value. When you use the SDK or API to upload media assets, you must Base64-decode the value before use. Only uploads by using the OSS native SDK or OSS API require you to parse UploadAddress yourself.

    LWNuLXNoYW5naGFpLmFsaXl1b****
    MediaId

    string

    The media asset ID.

    97dc17a5abc3668489b84ce9****
    MediaURL

    string

    The access URL of the media asset.

    If a CDN domain name is configured, a CDN URL is returned. Otherwise, an OSS URL is returned.

    Note

    If the returned MediaURL is inaccessible in a browser (403), you have enabled URL authentication for the VOD domain name. You can disable URL authentication or generate an authentication signature yourself.

    http://example.aliyundoc.com/watermark/****.mov?auth_key=****
    UploadAuth

    string

    The upload credential.

    Note

    The upload credential returned by the operation is a Base64-encoded value. When you use the SDK or API to upload media assets, you must Base64-decode the value before use. Only uploads by using the OSS native SDK or OSS API require you to parse UploadAuth yourself.

    UzFnUjFxNkZ0NUIZTaklyNWJoQ00zdHF****

    Examples

    Success response

    JSON format

    {
  "FileURL": "https://****.oss-cn-shanghai.aliyuncs.com/watermark/****.mov",
  "RequestId": "73254DE5-F260-4720-D06856B63C01****",
  "UploadAddress": "LWNuLXNoYW5naGFpLmFsaXl1b****",
  "MediaId": "97dc17a5abc3668489b84ce9****",
  "MediaURL": "http://example.aliyundoc.com/watermark/****.mov?auth_key=****",
  "UploadAuth": "UzFnUjFxNkZ0NUIZTaklyNWJoQ00zdHF****"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.