Register media assets from OSS with RegisterMedia - ApsaraVideo VOD - Alibaba Cloud - ApsaraVideo VOD

Operation description

To process audio and video files from an OSS bucket using ApsaraVideo VOD, you must first register them. After registration, you can use the media ID to initiate tasks such as transcoding, snapshotting, and AI processing.
You can register up to 10 OSS media files in a single API call. All files in the request must share the same storage location.
Media files uploaded directly to ApsaraVideo VOD are automatically transcoded by using the default template group if no other is specified. Registered media, however, is not automatically transcoded. To trigger transcoding, you must specify a transcoding template group ID during registration.
Re-registering a file returns its existing media ID and performs no other action.
Ensure that the media files you want to register have valid file extensions. Otherwise, the registration fails.

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:RegisterMedia

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
RegisterMetadatas	string	Yes	The metadata of the media to be registered. This parameter is a JSON string. You can specify metadata for up to 10 media files. For more information about the parameter structure, see the RegisterMetadata table below.	[{"FileURL":"https://****.oss-cn-shanghai.aliyuncs.com/video/test/video123.m3u8","Title":"VideoName"}]
TemplateGroupId	string	No	The ID of the transcoding template group. You can obtain the ID in one of the following ways: Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose configuration management > media processing configuration > transcoding template groups to view the transcoding template group ID. Call the AddTranscodeTemplateGroup operation to create a transcoding template group. The value of `TranscodeTemplateGroupId` in the response is the ID of the transcoding template group. Call the ListTranscodeTemplateGroup operation to query transcoding template groups. The value of `TranscodeTemplateGroupId` in the response is the ID of the transcoding template group. Note If you do not need to transcode the media, set this parameter to VOD_NO_TRANSCODE. Otherwise, the video status remains uploaded, and the media cannot be played. If you specify both `WorkflowId` and `TemplateGroupId`, `WorkflowId` takes precedence. For more information, see Workflows. This parameter triggers an asynchronous task. After the request is submitted, the task is queued for background processing and does not complete immediately.	ca3a8f6e49c87b65806709586****
UserData	string	No	Custom settings in a JSON string format, including configurations for message callbacks. For more information, see UserData. Note This operation does not generate a callback upon registration. However, the callback address specified in UserData is used for subsequent transcoding or snapshot tasks on the registered media, unless a different callback is specified for those tasks.	{"Extend":{"localId":"****","test":"www"}}
WorkflowId	string	No	The ID of the workflow. You can log on to the ApsaraVideo VOD console and choose configuration management > media processing configuration > workflows in the left-side navigation pane to view the workflow ID. Note If you specify both `WorkflowId` and `TemplateGroupId`, `WorkflowId` takes precedence. For more information, see Workflows. This parameter triggers an asynchronous task. After the request is submitted, the task is queued for background processing and does not complete immediately.	637adc2b7ba51a83d841606f8****
EnableFirstFrameCover	boolean	No
GenerateThumbnail	boolean	No

RegisterMetadata

Specifies the metadata for the media you want to register.

Parameter	Type	Required	Description
FileURL	String	Yes	The source file URL. You can call the GetMezzanineInfo operation to obtain the URL. The URL must not exceed 1,024 bytes in length and the filename must be globally unique. If you register a file with the same name, the operation returns the unique media ID associated with it. The URL consists of the public endpoint of an OSS bucket followed by the object name.
Title	String	Yes	The title of the media. The title can be up to 128 bytes in length and must be UTF-8 encoded.
Description	String	No	The description of the media. The description can be up to 1,024 bytes in length and must be UTF-8 encoded.
Tags	String	No	The media tags. You can specify up to 16 tags, separated by commas (,). Each tag can be up to 32 bytes and must be UTF-8 encoded.
CoverURL	String	No	The URL of the cover image. The URL must not exceed 1,024 bytes in length.
CateId	Long	No	The category ID. You can obtain the ID in one of the following ways: Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose configuration management > media asset configuration > category management to view the category ID. Call the AddCategory operation to create a category. The value of `CateId` in the response is the category ID. Call the GetCategories operation to query categories. The value of `CateId` in the response is the category ID.
ReferenceId	String	No	A custom ID. It can contain lowercase letters, uppercase letters, digits, hyphens (-), and underscores (_). The ID must be 6 to 64 characters in length and must be unique within your account.

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	14F43C5C-8033-448B-AD04F64E5098****
FailedFileURLs	array	A list of URLs for the files that failed to be registered.
	string	A list of URLs for the files that failed to be registered.	["http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"]
RegisteredMediaList	array<object>	A list of all media successfully processed in the request, including both newly registered and previously registered files.
	object	The registration details.
NewRegister	boolean	Indicates whether the media was newly registered or was already registered. true: Newly registered. false: Already registered.	false
FileURL	string	The OSS file URL.	http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4
MediaId	string	The media ID. For audio or video files, this ID corresponds to the VideoId.	d97af32828084d1896683b1aa38****

Examples

Success response

JSON format

{
  "RequestId": "14F43C5C-8033-448B-AD04F64E5098****",
  "FailedFileURLs": [
    "[\"http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4\"]"
  ],
  "RegisteredMediaList": [
    {
      "NewRegister": false,
      "FileURL": "http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4",
      "MediaId": "d97af32828084d1896683b1aa38****"
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.