Obtains a URL and a credential for uploading an image.

Description

  • You must obtain a URL and a credential before you upload a media file to ApsaraVideo VOD. ApsaraVideo VOD provides multiple upload methods. You can upload files by using server upload SDKs, client upload SDKs, URLs, Object Storage Service (OSS) API, or OSS SDKs. Each upload method has different requirements for obtaining upload URLs and credentials. For more information, see the "Usage notes" section of the Upload URLs and credentials topic.
  • The upload credential is not automatically updated when you upload an image. By default, an upload credential is valid for 3,000 seconds before it expires. If your credential expires, call this operation again to obtain the credential.
  • You can call the CreateUploadAttachedMedia operation to upload image watermarks.
  • You can configure a callback for ImageUploadComplete to receive notifications about the image upload status.

QPS limit

You can call this operation up to 100 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limit.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateUploadImage

The operation that you want to perform. Set the value to CreateUploadImage.

Title String No mytitle

The title of the image. Take note of the following items:

  • The title can be up to 128 characters in length.
  • The value must be encoded in UTF-8.
ImageType String Yes default

The type of the image. Valid values:

  • default: the default image type.
  • cover: the thumbnail.
Note Only images of the default type can be managed in the ApsaraVideo VOD console.
ImageExt String No png

The file name extension of the image. Default value: png. Valid values:

  • png
  • jpg
  • jpeg
  • gif
Tags String No Test

The tags of the image. Take note of the following items:

  • Each tag can be up to 32 characters in length.
  • You can specify a maximum of 16 tags for an image.
  • Separate multiple tags with commas (,).
  • The value must be encoded in UTF-8.
StorageLocation String No outin-****..oss-cn-shanghai.aliyuncs.com

The storage location. Perform the following operations to obtain the storage location:

Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Configuration Management > Media Management > Storage. On the Storage page, view the storage location.

Note If you specify a storage location, video files are uploaded to the specified location.
CateId Long No 100036****

The category ID of the image. You can use one of the following methods to obtain the category ID:

  • Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Configuration Management > Media Management > Categories. On the Categories page, you can view the category ID of the image.
  • Obtain the value of CateId from the response to the AddCategory operation.
  • Obtain the value of CateId from the response to the GetCategories operation.
UserData String No null

The custom configurations. For example, you can specify callback configurations and upload acceleration configurations. The value is a JSON string. For more information, see the "UserData: specifies the custom configurations for media upload" section of the Request parameters topic.

Note

  • The callback configurations take effect only after you specify the HTTP callback URL and select specific callback events in the ApsaraVideo VOD console. For more information about how to configure HTTP callback settings in the ApsaraVideo VOD console, see Configure callback settings.

  • To use the upload acceleration feature, submit a ticket to enable this feature. For more information, see Overview.
Description String No Image upload test

The description of the image.

  • The description can be up to 1,024 characters in length.
  • The value must be encoded in UTF-8.
AppId String No app-1000000

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

Response parameters

Parameter Type Example Description
FileURL String http://example.aliyundoc.com/cover/2017-34DB-4F4C-9373-003AA060****.png

The OSS URL of the file. The URL does not contain the information used for URL signing. You can set FileUrl to this URL when you call the AddWatermark operation.

RequestId String 25818875-5F78-AEF6-D7393642****

The ID of the request.

UploadAddress String eyJTZWN1cmuIjoiQ0FJU3p3TjF****

The upload URL.

Note The returned upload URL is a Base64-encoded URL. You must decode the Base64-encoded upload URL before you use an SDK or call an API operation to upload media files. You need to parse UploadAddress only if you use the OSS SDK or call an OSS API operation to upload media files.
ImageURL String http://example.aliyundoc.com/cover/2017-34DB-4F4C-9373-003AA060****.png

The URL of the image.

Note If you enable the URL signing feature in ApsaraVideo VOD, the returned URL may not be accessible from a browser and an HTTP 403 status code may be returned. To resolve this issue, you can disable the URL signing feature or generate a signed URL.
ImageId String 93ab850b4f6f46e91d24d81d4****

The ID of the image file.

UploadAuth String eyJFbmmRCI6Im****

The upload credential.

Note The returned upload credential is a Base64-encoded value. You must decode the Base64-encoded credential before you use an SDK or call an API operation to upload media files. You need to parse UploadAuth only if you use the OSS SDK or call an OSS API operation to upload media files.

Examples

Sample requests

http(s)://vod.cn-shanghai.aliyuncs.com/?Action=CreateUploadImage
&Title=mytitle
&ImageType=default
&ImageExt=png
&Tags=Test
&StorageLocation=outin-****..oss-cn-shanghai.aliyuncs.com
&UserData={"MessageCallback":{"CallbackURL":"http://example.aliyundoc.com"},"Extend":{"localId":"xxx","test":"www"}}
&Description=Image upload test
&AppId=app-1000000
&Common request parameters

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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

For a list of error codes, visit the API Error Center.

Sample code of SDKs for various languages

We recommend that you use a server-side SDK to call this operation. For more information about the sample code that is used to call this operation in various languages, see the following topics: