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
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.
Operation | Access level | Resource type | Condition key | Associated operation |
---|---|---|---|---|
ice:RegisterMediaInfo | create | *All Resources * |
| none |
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
InputURL | string | Yes | 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:
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.
vod://***20b48fb04483915d4f2cd8ac**** | |
MediaType | string | No | The type of the media asset. Valid values:
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 |
BusinessType | string | No | The business type of the media asset. Valid values:
| opening |
Title | string | No | The title. If you do not specify this parameter, a default title is automatically generated based on the date.
| defaultTitle |
Description | string | No | The description of the media asset.
| defaultDescription |
MediaTags | string | No | The tags of the media asset.
| tag1,tag2 |
CoverURL | string | No | The thumbnail URL of the media asset.
| http://example-bucket.oss-cn-shanghai.aliyuncs.com/example.png |
UserData | string | No | The user data. You can specify a custom callback URL. For more information.
| |
Overwrite | boolean | No | 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 |
ClientToken | string | No | The client token that is used to ensure the idempotence of the request. The value must be a UUID that contains 32 characters. | ****0311a423d11a5f7dee713535**** |
RegisterConfig | string | No | 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" } |
CateId | long | No | The category ID. | 3048 |
WorkflowId | string | No | The workflow ID. | ******b4fb044839815d4f2cd8****** |
ReferenceId | string | No | 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 |
SmartTagTemplateId | string | No | The ID of the smart tagging template. Valid values:
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
Examples
Sample success responses
JSON
format
{
"RequestId": "******5A-CAAC-4850-A3AF-B74606******",
"MediaId": "******b48fb04483915d4f2cd8******"
}
Error codes
HTTP status code | Error code | Error message |
---|---|---|
403 | Forbidden | User not authorized to operate on the specified resource. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|---|---|
2024-04-24 | The Error code has changed. The request parameters of the API has changed | View Change Details |
2023-04-11 | The Error code has changed | View Change Details |
2021-04-07 | The Error code has changed. The request parameters of the API has changed | View Change Details |