All Products
Search

This Product

    ApsaraVideo VOD:CreateUploadVideo

    Document Center

    ApsaraVideo VOD:CreateUploadVideo

    Last Updated:Dec 09, 2025

    ApsaraVideo VOD provides upload URLs and credentials to authorize uploads and ensure security. When you call this operation to obtain the upload URL and credential, a media ID (MediaId), also known as a video ID (VideoId), is automatically created to manage the audio or video asset.

    Operation description

    • Before you call this operation, make sure that you understand the billing methods and pricing of ApsaraVideo VOD. Uploading media assets to ApsaraVideo VOD incurs storage fees. For more information, see Media asset storage billing. If you enable transfer acceleration, you are also charged upload acceleration fees. For more information, see Storage transfer acceleration billing. Storage fees are charged after the file is successfully uploaded. Acceleration fees are charged when you upload a file after the feature is enabled. Calling this operation does not incur fees.

    • Obtaining an upload URL and credentials is a core feature of ApsaraVideo VOD and a required step for every upload. ApsaraVideo VOD provides multiple upload methods, and the requirements for obtaining the URL and credentials vary for each method. For more information, see Upload URL and credentials.

    • This operation is used only to obtain an upload URL and credentials and to create a media asset record. It is not used to upload files. For a complete example of how to upload a media asset by calling an API operation, see Upload media assets using ApsaraVideo VOD API operations.

    • You can use this operation to obtain upload URLs and credentials for both video and audio files. For more information, see Upload URL and credentials.

    • If an upload credential expires, you can call the RefreshUploadVideo operation to obtain a new one. The default validity period is 3000 seconds.

    • After the upload is complete, you can configure a callback to receive upload event notifications or call the GetMezzanineInfo operation to check the file status and determine whether the upload was successful.

    • Use the VideoId parameter returned by this operation for media asset lifecycle management or ApsaraVideo Media Processing.

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

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    CoverURL

    string

    No

    The URL of the custom video thumbnail.

    https://example.aliyundoc.com/image/D22F553TEST****.jpeg
    Description

    string

    No

    The description of the audio or video file that is displayed in ApsaraVideo VOD after the upload is complete.

    • The description can be up to 1,024 characters in length.

    • The value must be encoded in UTF-8.

    UploadTest
    FileName

    string

    Yes

    The path of the source audio or video file to upload.

    • The file name must include the file extension. The file extension is not case-sensitive.

    • For more information about supported file extensions, see Upload overview.

    D:\video_01.mp4
    FileSize

    integer

    No

    The size of the source audio or video file. Unit: bytes.

    123
    Title

    string

    Yes

    The title of the audio or video file that is displayed in ApsaraVideo VOD after the upload is complete.

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

    • The value must be encoded in UTF-8.

    UploadTest
    CateId

    integer

    No

    The category ID. You can obtain the category ID in one of the following ways:

    • Log on to the ApsaraVideo VOD console. In the navigation pane, choose Configuration Management > Media Management Configuration > Category Management to view the category ID.

    • The value of the CateId parameter that is returned after you call the AddCategory operation to create a category.

    • The value of the CateId parameter that is returned after you call the GetCategories operation to query categories.

    100036****
    Tags

    string

    No

    The tags of the audio or video file.

    • A maximum of 16 tags can be added.

    • Separate multiple tags with commas (,).

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

    • The value must be encoded in UTF-8.

    tag1,tag2
    UserData

    string

    No

    The custom settings. This is a JSON string that supports settings such as message callbacks and transfer acceleration. For more information, see UserData.

    Note

    • To use the message callback feature, you must configure a webhook address and select the corresponding event types in the ApsaraVideo VOD console. Otherwise, the callback settings do not take effect. For more information about how to configure a webhook in the console, see Callback settings.

    • To use the upload acceleration feature, you must fill out a form in Yida to request activation. For more information, see Upload instructions.

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

    string

    No

    The ID of the transcoding template group. You can obtain the ID in one of the following ways:

    • Log on to the ApsaraVideo VOD console. In the navigation pane, choose Configuration Management > Media Processing Configuration > Transcoding Template Groups to view the ID of the transcoding template group.

    • The value of the TranscodeTemplateGroupId parameter that is returned after you call the AddTranscodeTemplateGroup operation.

    • The value of the TranscodeTemplateGroupId parameter that is returned after you call the ListTranscodeTemplateGroup operation.

    Note

    • If you specify both `WorkflowId` and `TemplateGroupId`, `WorkflowId` takes precedence.

    • If you do not specify this parameter, the default transcoding template group is used. If you specify this parameter, the specified transcoding template group is used.

    • If you set this parameter to the ID of the system-built-in No Transcoding template group, you receive only the VideoUploadComplete event notification after the audio or video file is uploaded. You do not receive the TranscodeComplete event notification.

    • To ensure normal playback, if you set this parameter to the ID of the system-built-in No Transcoding template group, only files in the MP4, FLV, MP3, M3U8, and WEBM formats can be played without transcoding after they are uploaded. Files in other formats can only be stored. Pay attention to the file extension in `FileName`. If you use ApsaraVideo Player, the player version must be 3.1.0 or later.

    405477f9e214d19ea2c7c854****
    WorkflowId

    string

    No

    The workflow ID. Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing Configuration > Workflow Management to view the workflow ID.

    Note

    If you specify both `WorkflowId` and `TemplateGroupId`, `WorkflowId` takes precedence. For more information, see Workflows.

    613efff3887ec34af685714cc461****
    StorageLocation

    string

    No

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

    Note

    If you do not specify this parameter, the audio or video file is uploaded to the default storage address. If no default storage address is configured, the file is uploaded to the first storage address in the storage list. If you specify this parameter, the file is uploaded to the specified storage address.

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

    string

    No

    The ID of the application. Default value: app-1000000. For more information, see Multi-application service.

    app-1000000
    ReferenceId

    string

    No

    A custom ID. It can contain lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_). The ID must be 6 to 64 characters in length and unique for each user.

    123-123

    Response elements

    Element

    Type

    Description

    Example

    object

    The response parameters.

    RequestId

    string

    The request ID.

    25818875-5F78-4AF6-04D5-D7393642****
    UploadAddress

    string

    The upload URL.

    Note

    The upload URL returned by the operation is Base64-encoded. You must Base64-decode the URL before you use an SDK or an API operation to upload the media asset. You must parse `UploadAddress` only when you upload a media asset using an Object Storage Service (OSS) native SDK or by calling an OSS API operation.

    eyJTZWN1cml0a2VuIjoiQ0FJU3p3TjF****
    VideoId

    string

    The ID of the audio or video file. You can use this ID as a request parameter when you call other operations, such as operations for media asset management, media processing, and media review.

    93ab850b4f6f54b6e91d24d81d44****
    UploadAuth

    string

    The upload credential.

    Note

    The upload credential returned by the operation is Base64-encoded. You must Base64-decode the credential before you use an SDK or an API operation to upload the media asset. You must parse `UploadAuth` only when you upload a media asset using an OSS native SDK or by calling an OSS API operation.

    eyJFbmRwb2ludCI6Imm****

    Examples

    Success response

    JSON format

    {
  "RequestId": "25818875-5F78-4AF6-04D5-D7393642****",
  "UploadAddress": "eyJTZWN1cml0a2VuIjoiQ0FJU3p3TjF****",
  "VideoId": "93ab850b4f6f54b6e91d24d81d44****",
  "UploadAuth": "eyJFbmRwb2ludCI6Imm****"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.