All Products
Document Center

ApsaraVideo VOD:RegisterMedia

Last Updated:May 19, 2022


You can call this operation to register media objects (including audios and videos) in OSS buckets that have access to ApsaraVideo for VOD. After a media object is successfully registered as a media asset, you can submit a transcoding or video snapshot based on the media ID.


  • You can register a maximum of 10 OSS media objects that have the same storage location at a time.
  • After a media asset is registered, this operation does not automatically trigger a transcoding job if the transcoding template group ID is not specified. If the transcoding template group ID is specified, the system uses the specified template group to transcode the media asset. This processing is different from video upload.
  • If you submit a media object that has been registered, this operation returns only the unique media ID associated with the media object, without other processing.

Request parameters

ActionStringYesThe operation that you want to perform. Set the value to RegisterMedia.
RegisterMetadatas RegisterMetadata[]YesThe metadata of the media asset. The value is a JSON-formatted string. You can specify the metadata for a maximum of 10 media assets at a time.
TemplateGroupIdStringNoThe transcoding template group ID.
If you set this parameter, the system uses the specified template group to transcode the media asset. To view the template group ID, log on to the ApsaraVideo for VOD console and choose Global Settings > Transcode in the left-side navigation pane.
UserDataUserDataNoThe custom configurations, such as the callback configuration for event notifications. The value is a JSON-formatted string.

Note: Request parameters (such as Title, Description, and Tags) cannot contain emoticons.

Response parameters

RequestIdStringThe GUID generated by Alibaba Cloud for the request.
RegisteredMediaList RegisteredMedia[]The list of requested media objects that have been successfully registered, including newly registered and repeatedly registered media objects.
FailedFileURLs String[] The URL list of requested media objects that failed to be registered.


MediaId StringThe media ID registered with ApsaraVideo for VOD. If the registered media object is an audio or video, this parameter corresponds to the VideoId parameter of ApsaraVideo for VOD.
FileURL StringThe OSS URL of the media object.
NewRegister BooleanIndicates whether the media object is newly registered or repeatedly registered. Valid values: true: indicates that the media object is newly registered. false: indicates that the media object is repeatedly registered.


Sample requests

  1.[{"FileURL":"","Title":"Test title"}]&Format=JSON&<Common request parameters>

Note: For more information about common request parameters, see Common parameters.

Sample responses

JSON format

  1. {
  2. "RequestId":"14F43C5C-8033-43E7-B48B-AD04F64E5098",
  3. "RegisteredMediaList": [
  4. {
  5. "MediaId":"d97af328280842229aed1896683b1aa38",
  6. "FileURL":"",
  7. "NewRegister":true
  8. },
  9. {
  10. "MediaId":"d97af328280842229aed1896683b1aa38",
  11. "FileURL":"",
  12. "NewRegister":false
  13. }
  14. ],
  15. "FailedFileURLs":[
  16. ""
  17. ]
  18. }

Error codes

The following table lists the error code that this operation can return. For more information, see Error codes.

Error codeError messageHTTP status codeDescription
InvalidTemplateGroupId.NotFoundThe TemplateGroupId does not exist.404The error message returned when the specified template group ID does not exist.