All Products
Search

This Product

    ApsaraVideo VOD:CreateUploadImage

    Document Center

    ApsaraVideo VOD:CreateUploadImage

    Last Updated:Jul 21, 2026

    Retrieves the upload URL and upload credential for uploading an image to ApsaraVideo VOD, and creates image information. ApsaraVideo VOD issues upload URLs and credentials to ensure authorization and security, prevent malicious uploads, and supports automatic creation of an image ID (ImageId) for management. You can invoke this operation to obtain the upload URL and credential and create image 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 and transfer acceleration, uploading media files to ApsaraVideo VOD also incurs upload acceleration fees. For more information, see Storage and transfer acceleration billing.

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

    • Refreshing the upload URL and credential is not supported for image uploads. If the image upload credential expires (the default validity period is 3000 seconds), call this operation again to obtain a new upload URL and credential.

    • You can configure callbacks to receive event notifications for image upload completion to determine whether the upload is successful.

    • Retrieving the upload URL and credential is a core operation of ApsaraVideo VOD and is required for every upload. ApsaraVideo VOD provides multiple upload methods, each with different requirements for retrieving the upload URL and credential. For more information, see 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:CreateUploadImage

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    Title

    string

    No

    The title of the image. Rules:

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

    • The title must be encoded in UTF-8.

    mytitle
    ImageType

    string

    Yes

    The type of the image. Valid values:

    • default (default): a common image.

    • cover: a video thumbnail.

    Note

    The ApsaraVideo VOD console supports viewing and managing only images of the default type.

    default
    ImageExt

    string

    No

    The file name extension of the image source file to upload. Valid values:

    • png (default)

    • jpg

    • jpeg

    • gif

    • heic

    • webp

    png
    OriginalFileName

    string

    No

    The address of the image source file to upload.

    Note

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

    D:\picture_01
    Tags

    string

    No

    The tags of the image. Rules:

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

    • You can specify up to 16 tags.

    • Separate multiple tags with commas (,).

    • The tags must be encoded in UTF-8.

    Test
    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 > Storage to view the storage address.

    Note

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

    outin-****..oss-cn-shanghai.aliyuncs.com
    CateId

    integer

    No

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

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

    • Obtain the value of CateId from the response when you call the AddCategory operation to create a category.

    • Obtain the value of CateId from the response when you call the GetCategories operation to query categories.

    100036****
    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 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"}}
    Description

    string

    No

    The description of the image.

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

    • The description must be encoded in UTF-8.

    Image upload test
    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 image to the specified application. For more information, see Multi-application.

    app-1000000

    Response elements

    Element

    Type

    Description

    Example

    object

    The response parameters.

    FileURL

    string

    The OSS URL of the image file (without authentication).

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

    http://example.aliyundoc.com/cover/2017-34DB-4F4C-9373-003AA060****.png
    RequestId

    string

    The request ID.

    25818875-5F78-AEF6-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, decode the value in Base64 before use. Only uploads by using the OSS native SDK or OSS API require you to parse UploadAddress.

    eyJTZWN1cmuIjoiQ0FJU3p3TjF****
    ImageURL

    string

    The access URL of the image.

    Note

    If the returned ImageURL is inaccessible in a browser (403 error), URL authentication is enabled for your VOD domain name. Disable URL authentication or generate a signed URL.

    http://example.aliyundoc.com/cover/2017-34DB-4F4C-9373-003AA060****.png
    ImageId

    string

    The image ID. This ID can be used as a request parameter for operations such as GetImageInfo, GetImageInfos, UpdateImageInfos, and DeleteImage.

    93ab850b4f6f46e91d24d81d4****
    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, decode the value in Base64 before use. Only uploads by using the OSS native SDK or OSS API require you to parse UploadAuth.

    eyJFbmmRCI6Im****

    Examples

    Success response

    JSON format

    {
  "FileURL": "http://example.aliyundoc.com/cover/2017-34DB-4F4C-9373-003AA060****.png",
  "RequestId": "25818875-5F78-AEF6-D7393642****",
  "UploadAddress": "eyJTZWN1cmuIjoiQ0FJU3p3TjF****",
  "ImageURL": "http://example.aliyundoc.com/cover/2017-34DB-4F4C-9373-003AA060****.png",
  "ImageId": "93ab850b4f6f46e91d24d81d4****",
  "UploadAuth": "eyJFbmmRCI6Im****"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.