All Products
Search
Document Center

ApsaraVideo VOD:RegisterMedia

Last Updated:Mar 18, 2024

Registers media files. After you add an Object Storage Service (OSS) bucket to ApsaraVideo VOD, you must register the media files in the bucket to generate the required information before you use features such as transcoding and snapshot capture on the media files.

Operation description

  • After you add an OSS bucket to ApsaraVideo VOD, you must register media files in the OSS bucket to generate the required information. Then, you can use media IDs for features such as transcoding, snapshot capture, and AI processing.use features such as xxx on media files by specifying their IDs?
  • You can register up to 10 media files in an OSS bucket in a request. The media files must be stored in the same bucket.
  • If you do not specify a transcoding template group ID when you upload a media file to ApsaraVideo VOD, the media file is automatically transcoded based on the default template group. If you do not specify a transcoding template group ID after you register a media file, the media file is not automatically transcoded. The registered media files are automatically transcoded only if you specify a transcoding template group ID.
  • If the media file that you want to register has been registered, this operation returns only the unique media ID that is associated with the media file. No further operation is performed.
  • Make sure that the media file that you want to register has a valid suffix. Otherwise, the registration fails.

QPS limits

You can call this operation up to 50 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 limits on API operations.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

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:
    • The required resource types are displayed in bold characters.
    • 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
vod:RegisterMediaRead
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegisterMetadatasstringYes

The metadata of the media files. The value must be a JSON string. You can specify the metadata for up to 10 media files at a time. For more information about the metadata of media files, see the RegisterMetadata section of this topic.

[{"FileURL":"https://****.oss-cn-shanghai.aliyuncs.com/video/test/video123.m3u8","Title":"VideoName"}]
TemplateGroupIdstringNo

The ID of the transcoding template group. You can use one of the following methods to obtain the ID:

  • Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Configuration Management > Media Processing > Transcoding Template Groups. On the Transcoding Template Groups page, you can view the ID of the transcoding template group.
  • Obtain the value of the TranscodeTemplateGroupId parameter from the response to the AddTranscodeTemplateGroup operation that you called to create a transcoding template group.
  • Obtain the value of the TranscodeTemplateGroupId parameter from the response to the ListTranscodeTemplateGroup operation that you called to query transcoding template groups.
Note
  • If you do not need to transcode media files, set the TemplateGroupId parameter to VOD_NO_TRANSCODE. If you do not specify this configuration, errors occur on your files. If you need to transcode media files, specify the ID of the transcoding template group.

  • If you specify both WorkflowId and TemplateGroupId, the value of the WorkflowId parameter takes effect. For more information, see Workflows .

ca3a8f6e49c87b65806709586****
UserDatastringNo

The custom settings. The value must be a JSON string. You can configure settings such as message callbacks. For more information, see UserData .

Note You cannot configure callbacks for this operation. No callback message is returned after the media files are registered even if you configure callback settings for this parameter. If you configure callback settings for the UserData parameter when you create media processing jobs such as transcoding and snapshot capture jobs for the media file, the callback URL that you specified is used. If you do not configure callback settings when you create media processing jobs, the callback URL that you specified for the UserData parameter when you register the media file is used.
{"Extend":{"localId":"****","test":"www"}}
WorkflowIdstringNo

The ID of the workflow. To view the workflow ID, perform the following steps: Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Configuration Management > Media Processing > Workflows.

Note If you specify both WorkflowId and TemplateGroupId, the value of WorkflowId parameter takes effect. For more information, see Workflows .
637adc2b7ba51a83d841606f8****

RegisterMetadata

The following table describes the metadata of the media file.

ParameterTypeRequiredDescription
FileURLStringYesThe URL of the source file. You can call the GetMezzanineInfo operation to obtain the URL of the source file.The URL can be up to 1,024 bytes in length. The file name must be globally unique. If the media file has been registered, the unique media ID that is associated with the media file is returned.
TitleStringYesThe title of the media file. The title cannot exceed 128 bytes. The title must be encoded in UTF-8.
DescriptionStringNoThe description of the media file. The description can be up to 1,024 bytes in length. The description must be encoded in UTF-8.
TagsStringNoThe tags of the media file. Each tag can be up to 32 bytes in length. You can specify a maximum of 16 tags. Separate multiple tags with commas (,). The value must be encoded in UTF-8.
CoverURLStringNoThe URL of the thumbnail. The URL can be up to 1,024 bytes in length.
CateIdLongNoThe ID of the category. To obtain the category ID, perform the following steps:Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose Configuration Management > Media Management > Categories.Obtain the value of the CateId parameter from the response to the AddCategory operation that you called to create a category.Obtain the value of the CateId parameter from the response to the GetCategories operation that you called to query a category.

Response parameters

ParameterTypeDescriptionExample
object

The returned results.

RequestIdstring

The ID of the request.

14F43C5C-8033-448B-AD04F64E5098****
FailedFileURLsarray

The URLs of the media files that failed to be registered.

string

The URL of the media file that failed to be registered.

["http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"]
RegisteredMediaListobject []

The media files that are registered, including newly registered and repeatedly registered media files.

NewRegisterboolean

Indicates whether the media file is newly registered or repeatedly registered. Valid values:

  • true: The media file is newly registered.
  • false: The media file is repeatedly registered.
false
FileURLstring

The URL of the media file.

http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4
MediaIdstring

The ID of the media file that is registered with ApsaraVideo VOD. If the registered media file is an audio or video file, the value of this parameter is the same as that of the VideoId parameter.

d97af32828084d1896683b1aa38****

Examples

Sample success responses

JSONformat

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

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