All Products
Search

This Product

    ApsaraVideo VOD:CreateUploadVideo

    Document Center

    ApsaraVideo VOD:CreateUploadVideo

    Last Updated:Jul 21, 2026

    ApsaraVideo VOD issues the upload URL and upload credential to ensure authorization and security and prevent malicious uploads. During issuance, a media ID (MediaId), also called a video ID (VideoId), undergoes automatic creation for management. Invoke this operation to obtain the upload URL and upload credential, and create audio or video information.

    Operation description

    • Before you use this operation, make sure that you are familiar with 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 and transfer acceleration, uploading media files to ApsaraVideo VOD also incurs upload acceleration fees. For more information, see Storage and transfer acceleration billing. Storage fees are calculated from the time when the file is uploaded. Acceleration fees are calculated when you perform upload operations after the feature is enabled. Simply calling this operation does not incur fees.

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

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

    • This operation supports obtaining the upload URL and credential for both video and audio files. For more information, see Upload URLs and credentials.

    • If the upload credential expires (the default validity period is 3000 seconds), call the RefreshUploadVideo operation to obtain a new upload credential.

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

    • 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 thumbnail.

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

    string

    No

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

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

    • The value is encoded in UTF-8.

    UploadTest
    FileName

    string

    Yes

    The address of the audio or video source file to be uploaded.

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

    • For supported file name extensions, see Upload overview.

    D:\video_01.mp4
    FileSize

    integer

    No

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

    123
    Title

    string

    Yes

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

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

    • The value is encoded in UTF-8.

    UploadTest
    CateId

    integer

    No

    The category ID. You can obtain the category ID by using one of the following methods:

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

    • When you create a category by calling the AddCategory operation, the category ID is the value of the CateId parameter in the response.

    • When you query categories by calling 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 file.

    • You can specify up to 16 tags.

    • To specify multiple tags, separate them with commas (,).

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

    • The value is encoded in UTF-8.

    tag1,tag2
    UserData

    string

    No

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

    Note

    • To use the message callback 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. If no callback URL is specified for subsequent tasks, callbacks are sent to this address by default. To configure HTTP callbacks in the console, see Callback settings.

    • To use the upload acceleration feature, you must submit a Yida form to apply for 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 by using one of the following methods:

    • Log on to the ApsaraVideo VOD console and choose Configuration Management > Media Processing Configuration > Transcoding Template Groups to view the transcoding template group ID.

    • When you create a transcoding template group by calling the Create a transcoding template group operation, the transcoding template group ID is the value of the TranscodeTemplateGroupId parameter in the response.

    • When you query transcoding template groups by calling the Query transcoding configurations operation, the transcoding template group ID is the value of the TranscodeTemplateGroupId parameter in the response.

    Note

    • If both WorkflowId and TemplateGroupId are specified, WorkflowId takes precedence.

    • If this parameter is not specified, the default transcoding template group is used for transcoding. If a transcoding template group ID is specified, the specified template group is used for transcoding.

    • If this parameter is set to the built-in No Transcoding template group, only the Video Upload Complete event notification is sent after the audio or video file is uploaded. The Transcode Complete for a Single Definition event notification is not sent.

    • This parameter triggers an asynchronous task. After submission, the task is not immediately completed and is queued for asynchronous execution in the background.

    • To ensure normal playback, when the built-in No Transcoding template group is used, only the following formats support direct playback without transcoding after the audio or video file is uploaded: MP4, FLV, MP3, M3U8, and WEBM. Other formats support storage only (check the file name extension of 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 both WorkflowId and TemplateGroupId are specified, WorkflowId takes precedence. For more information, see Workflows.

    • This parameter triggers an asynchronous task. After submission, the task is not immediately completed and is queued for asynchronous execution in the background.

    613efff3887ec34af685714cc461****
    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 this parameter is not specified, the audio or video file is uploaded to the default storage address. If no default storage address exists, the file is uploaded to the first storage address in the storage list. If this parameter is specified, the audio or video file is uploaded to the specified storage address.

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

    string

    No

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

    app-1000000
    ReferenceId

    string

    No

    The custom ID. Only lowercase letters, uppercase letters, digits, hyphens, and underscores are supported. The length is 6 to 64 characters. The ID is unique at the user level.

    123-123
    EnableFirstFrameCover

    boolean

    No

    GenerateThumbnail

    boolean

    No

    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 this operation is a Base64-encoded value. When you use an SDK or API to upload media assets, you must Base64-decode the value before use. Only uploads by using the native OSS SDK or OSS API require you to parse UploadAddress.

    eyJTZWN1cml0a2VuIjoiQ0FJU3p3TjF****
    VideoId

    string

    The audio or video ID. This ID can be used as a request parameter for media asset management, media processing, and content moderation operations.

    93ab850b4f6f54b6e91d24d81d44****
    UploadAuth

    string

    The upload credential.

    Note

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

    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.