All Products
Search
Document Center

RegisterMedia

Last Updated: Aug 13, 2019

Description

You can call this operation to register media objects (including audio and video files) in OSS buckets connected to ApsaraVideo for VOD. After a media object is registered as a media asset, you can submit a transcoding or video snapshot job based on the media ID.

Restrictions

  • You can register a maximum of 10 OSS media objects that are in the same bucket 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

NameTypeRequiredDescription
ActionStringYesThe operation that you want to perform. Set this parameter to RegisterMedia.
RegisterMetadatas RegisterMetadata[]YesThe metadata of the media asset to be registered. The value is a JSON-formatted string. You can specify the metadata for a maximum of 10 media assets at a time.
TemplateGroupIdStringNoThe ID of the transcoding template group.
If you specify this parameter, the specified template group is used 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. The value is a JSON-formatted string.

RegisterMetadata

Specifies the metadata of the media asset to be registered. The values of the Title, Description, and Tags parameters cannot contain emoticons.

ParameterTypeRequiredDescription
FileURL StringYesThe URL of the mezzanine file. Length constraint: Maximum length of 1,024 bytes. Each file name must be globally unique. If the file name of a media asset to be added exists, the unique media ID associated with the file URL is returned.
Title StringNoThe title of the media asset. Length constraint: Maximum length of 128 bytes. Encoding: UTF-8. If you do not set this parameter, the file name in the file URL is used as the title by default.
Description StringNoThe description of the media asset. Length constraint: Maximum length of 1,024 bytes. Encoding: UTF-8.
Tags StringNoThe tag of the media asset. Length constraint per tag: Maximum length of 32 bytes. You can enter a maximum of 16 tags. Separate multiple tags with commas (,). Encoding: UTF-8.
CoverURL StringNoThe URL of the thumbnail. Length constraint: Maximum length of 1,024 bytes.
CateId Long NoThe ID of the category.

Example:

  1. RegisterMetadata={"FileURL":"https://xxxxx.oss-cn-shanghai.aliyuncs.com/xxxx/vod_sample.mp4", "Title":"Test title","TemplateGroupId":"30986d46d585e47e330567d9e907892f"}

Response parameters

NameTypeDescription
RequestIdStringThe ID of the request.
RegisteredMediaList RegisteredMedia[] The list of media objects that had been registered upon the current request, including newly registered media objects and media objects that had been registered before.
FailedFileURLs String[] The list of URLs of requested media objects that failed to be registered.

RegisteredMedia

Specifies the information about requested media objects that had been registered.

NameTypeDescription
MediaId StringThe media ID registered with ApsaraVideo for VOD. If the registered media object is an audio or video file, 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 was newly registered or had been registered before. Valid values: true: indicates that the media object was newly registered. false: indicates that the media object had been registered before.

API examples

Sample request

  1. http://vod.cn-shanghai.aliyuncs.com/?Action=RegisterMedia&MediaMetadatas=[{"FileURL":"https://xxxxx.oss-cn-shanghai.aliyuncs.com/xxxx/vod_sample.mp4","Title":"Test title"}]&Format=JSON&<Common request parameters>

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

Sample response

JSON format

  1. {
  2. "RequestId":"14F43C5C-8033-43E7-B48B-AD04F64E5098",
  3. "RegisteredMediaList": [
  4. {
  5. "MediaId":"d97af328280842229aed1896683b1aa38",
  6. "FileURL":"http://xxxx.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4",
  7. "NewRegister":true
  8. },
  9. {
  10. "MediaId":"d97af328280842229aed1896683b1aa38",
  11. "FileURL":"http://xxxx.oss-cn-shanghai.aliyuncs.com/vod_sample_02.mp4",
  12. "NewRegister":false
  13. }
  14. ],
  15. "FailedFileURLs":[
  16. "http://xxxx.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"
  17. ]
  18. }

Error codes

This operation also returns common errors. For more information about errors common to all operations, see common errors.

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

SDK examples

We recommend that you use a server SDK to call this operation. For more information about the sample code used to call this operation in various languages, see the following topics: