All Products
Search
Document Center

Intelligent Media Services:RegisterMediaInfo

Last Updated:Feb 07, 2025

Registers a media asset with Intelligent Media Services (IMS). IMS assigns an ID to the media asset. This operation asynchronously accesses the media asset service in which the media asset is stored to obtain the file information of the media asset based on the input URL. You can also specify basic information, such as the title, tags, and description, for the media asset. This operation returns the ID of the media asset. You can call the GetMediaInfo operation based on the ID to query the details of the media asset. You can set InputURL only to the URL of an Object Storage Service (OSS) file or an ApsaraVideo VOD media asset.

Operation description

Registering a media asset is an asynchronous job that takes 2 to 3 seconds. When the operation returns the ID of the media asset, the registration may have not be completed. If you call the GetMediaInfo operation at this time, you may fail to obtain the information about the media asset.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • For mandatory resource types, indicate with a prefix of * .
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ice:RegisterMediaInfocreate
*All Resources
*
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
InputURLstringYes

The URL of the media asset in another service. The URL is associated with the ID of the media asset in IMS. The URL cannot be modified once registered. The following types of URLs are supported:

  • OSS URL in one of the following formats:

http(s)://example-bucket.oss-cn-shanghai.aliyuncs.com/example.mp4

oss://example-bucket/example.mp4: In this format, it is considered by default that the region of the OSS bucket in which the media asset resides is the same as the region in which IMS is activated.

  • URL of an ApsaraVideo VOD media asset

vod://***20b48fb04483915d4f2cd8ac****

MediaTypestringNo

The type of the media asset. Valid values:

  • image
  • video
  • audio
  • text

We recommend that you specify this parameter based on your business requirements. If you set InputURL to an OSS URL, the media asset type can be automatically determined based on the file name extension. For more information .

video
BusinessTypestringNo

The business type of the media asset. Valid values:

  • subtitles
  • watermark
  • opening
  • ending
  • general
opening
TitlestringNo

The title. If you do not specify this parameter, a default title is automatically generated based on the date.

  • The value can be up to 128 bytes in length.
  • The value must be encoded in UTF-8.
defaultTitle
DescriptionstringNo

The description of the media asset.

  • The value can be up to 1,024 bytes in length.
  • The value must be encoded in UTF-8.
defaultDescription
MediaTagsstringNo

The tags of the media asset.

  • Up to 16 tags are supported.
  • Separate multiple tags with commas (,).
  • Each tag can be up to 32 bytes in length.
  • The value must be encoded in UTF-8.
tag1,tag2
CoverURLstringNo

The thumbnail URL of the media asset.

  • The value can be up to 128 bytes in length.
  • The value must be encoded in UTF-8.
http://example-bucket.oss-cn-shanghai.aliyuncs.com/example.png
UserDatastringNo

The user data. You can specify a custom callback URL. For more information.

  • The value can be up to 1,024 bytes in length.
  • The value must be encoded in UTF-8.
  • The value must be in the JSON format.
OverwritebooleanNo

Specifies whether to overwrite the media asset that has been registered by using the same URL. Default value: false. Valid values:

- true: If a media asset has been registered by using the same URL, the original media asset is deleted and the new media asset is registered.

- false: If a media asset has been registered by using the same URL, the new media asset is not registered. A URL cannot be used to register multiple media assets.

true
ClientTokenstringNo

The client token that is used to ensure the idempotence of the request. The value must be a UUID that contains 32 characters.

****0311a423d11a5f7dee713535****
RegisterConfigstringNo

The registration configurations.

By default, a sprite is generated for the media asset. You can set NeedSprite to false to disable automatic sprite generation.

By default, a snapshot is generated for the media asset. You can set NeedSnapshot to false to disable automatic snapshot generation.

{ "NeedSprite": "false" }
CateIdlongNo

The category ID.

3048
WorkflowIdstringNo

The workflow ID.

******b4fb044839815d4f2cd8******
ReferenceIdstringNo

The custom ID. The ID can be 6 to 64 characters in length and can contain only letters, digits, hyphens (-), and underscores (_). Make sure that the ID is unique among users.

123-123
SmartTagTemplateIdstringNo

The ID of the smart tagging template. Valid values:

  • S00000101-300080: the system template that supports natural language processing (NLP) for content recognition.
  • S00000103-000001: the system template that supports NLP for content recognition and all tagging capabilities.
  • S00000103-000002: the system template that supports all tagging capabilities but does not support NLP for content recognition.

After you configure this parameter, a smart tag analysis task is automatically initiated after the media asset is registered. For more information about the billable items.

S00000101-300080

Response parameters

ParameterTypeDescriptionExample
object

The response parameters.

RequestIdstring

The request ID.

******5A-CAAC-4850-A3AF-B74606******
MediaIdstring

The ID of the media asset in IMS.

******b48fb04483915d4f2cd8******

Examples

Sample success responses

JSONformat

{
  "RequestId": "******5A-CAAC-4850-A3AF-B74606******",
  "MediaId": "******b48fb04483915d4f2cd8******"
}

Error codes

HTTP status codeError codeError message
403ForbiddenUser not authorized to operate on the specified resource.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-04-24The Error code has changed. The request parameters of the API has changedView Change Details
2023-04-11The Error code has changedView Change Details
2021-04-07The Error code has changed. The request parameters of the API has changedView Change Details