All Products
Search

This Product

    ApsaraVideo VOD:CreateUploadVideo

    Document Center

    ApsaraVideo VOD:CreateUploadVideo

    Last Updated:Mar 31, 2026

    ApsaraVideo VOD provides an upload address and credential for authorized and secure uploads. The service also creates a media ID (or video ID) for media management. Call this operation to get the upload address and credential, and to initialize a media asset.

    Operation description

    • Before you use this operation, understand the billing methods and pricing of ApsaraVideo VOD. Uploading media assets to ApsaraVideo VOD incurs storage fees. For more information, see Storage billing. If you have enabled storage and transfer acceleration, upload acceleration fees are also incurred. For more information, see Billing of storage and transfer acceleration. Storage fees apply as soon as a file uploads successfully. Acceleration fees are charged for uploads after you enable the feature. Calling this operation is free of charge.

    • Obtaining an upload address and credential is required for all uploads. ApsaraVideo VOD supports multiple upload methods, and how you obtain them depends on the chosen method. For more information, see Upload address and credential.

    • This operation only retrieves an upload address and credential, and initializes the media asset. It does not upload the file. For a complete API upload example, see Upload media assets by using the VOD API.

    • This operation retrieves the upload address and credential for video and audio files. For more information, see Upload address and credential.

    • If an upload credential expires (it is valid for 3,000 seconds by default), call the RefreshUploadVideo operation to get a new one.

    • 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 verify the upload.

    • The VideoId parameter returned by this operation can be used for media asset lifecycle management or 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 cover.

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

    string

    No

    The description of the audio or video file. This is displayed in the ApsaraVideo VOD console after the upload completes.

    • 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 to the source audio or video file.

    • The file extension is required and is not case-sensitive.

    • For a list of supported file extensions, see Upload overview.

    D:\video_01.mp4
    FileSize

    integer

    No

    The size of the source file, in bytes.

    123
    Title

    string

    Yes

    The title of the audio or video file. This is displayed in the ApsaraVideo VOD console after the upload completes.

    • 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 and choose Configuration Management > Media Management > Category Management to view the category ID.

    • Call the AddCategory operation. The category ID is the value of the CateId parameter in the response.

    • Call the GetCategories operation. The category ID is the value of the CateId parameter in the response.

    100036****
    Tags

    string

    No

    The tags of the audio or video.

    • You can add a maximum of 16 tags.

    • Separate multiple tags with a comma (,).

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

    • The value must be encoded in UTF-8.

    tag1,tag2
    UserData

    string

    No

    Custom settings in JSON format. This parameter supports features such as message callbacks and upload acceleration. For more information, see UserData.

    Note

    • To use message callbacks, you must configure an HTTP callback URL and select the corresponding event types in the ApsaraVideo VOD console. Otherwise, callbacks will not be sent. If you do not specify a callback URL for subsequent tasks, notifications are sent to this default address. For instructions on how to configure HTTP callbacks, see Callback settings.

    • To use the upload acceleration feature, you must submit a ticket to apply for it. 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 and choose Configuration Management > Media Processing > Transcoding Template Groups to view the transcoding template group ID.

    • Call the AddTranscodeTemplateGroup operation. The ID is the value of the TranscodeTemplateGroupId parameter in the response.

    • Call the ListTranscodeTemplateGroup operation. The ID is the value of the TranscodeTemplateGroupId parameter in the response.

    Note

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

    • If you omit this parameter, the default transcoding template group is used. Otherwise, the specified group is used for transcoding.

    • If you use the ID of the built-in No Transcoding template group, you receive a VideoUploadComplete notification instead of a TranscodeComplete notification after the video uploads.

    • When using the built-in No Transcoding template group, only files in MP4, FLV, MP3, M3U8, and WEBM formats can be played directly without transcoding. Other file formats are stored but are not playable. This is determined by the file extension in the FileName parameter. Direct playback requires ApsaraVideo Player 3.1.0 or later.

    405477f9e214d19ea2c7c854****
    WorkflowId

    string

    No

    The workflow ID. To find the workflow ID, log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing > Workflow Management.

    Note

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

    613efff3887ec34af685714cc461****
    StorageLocation

    string

    No

    The storage location. To find the storage location, log on to the ApsaraVideo VOD console and choose Configuration Management > Media Management > Storage Management.

    Note

    If you omit this parameter, the media file is uploaded to the default storage location. If no default storage location is configured, the file is uploaded to the first location in the storage list. Otherwise, the file is uploaded to the specified storage location.

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

    string

    No

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

    app-1000000
    ReferenceId

    string

    No

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

    123-123

    Response elements

    Element

    Type

    Description

    Example

    object

    The response body.

    RequestId

    string

    The request ID.

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

    string

    The upload address.

    Note

    The upload address is a Base64-encoded string. You must decode it before you can use it to upload a media asset with an SDK or an API. Parsing is required only if you use an Object Storage Service (OSS) native SDK or call an OSS API to upload the media asset.

    eyJTZWN1cml0a2VuIjoiQ0FJU3p3TjF****
    VideoId

    string

    The ID of the audio or video file. This ID can be used as a request parameter for media asset management, media processing, and media review.

    93ab850b4f6f54b6e91d24d81d44****
    UploadAuth

    string

    The upload credential.

    Note

    The upload credential is a Base64-encoded string. You must decode it before you can use it to upload a media asset with an SDK or an API. Parsing is required only if you use an Object Storage Service (OSS) native SDK or call an OSS API to upload the media asset.

    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.