Registers media files.

You can call this operation to register audio and video files in Object Storage Service (OSS) buckets that are used for ApsaraVideo VOD. After a media file is registered, you can specify the media ID to submit transcoding jobs and snapshot jobs. For more information, see SubmitTranscodeJobs and SubmitSnapshotJob.

Note
  • You can register up to 10 OSS media files that have the same OSS URL at a time.
  • Compared with video upload, this operation does not trigger a transcoding job after a media file is registered 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 file.
  • If you submit a media file that is registered, this operation returns only the unique media ID that is associated with the media file. No further processing is performed.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes RegisterMedia

The operation that you want to perform. Set the value to RegisterMedia.

RegisterMetadatas String Yes [{"FileURL":"https://bucketName.oss-cn-shanghai.aliyuncs.com/video/test/video.m3u8","Title":"VideoName"}]

The metadata of the media file that you want to register. The value is a JSON string. You can specify the metadata for a maximum of 10 media files at a time. For more information about the metadata of media files, see the following RegisterMetadata table.

TemplateGroupId String No ca3a8f6e49c8*****7b65806709586

The ID of the transcoding template group. You can obtain the ID by calling the AddTranscodeTemplateGroup operation.

Note
  • If you do not want to transcode the media files, set TemplateGroupId to VOD_NO_TRANSCODE. Otherwise, an exception occurs during video playback.
  • If you want to transcode the media files, log on to the ApsaraVideo VOD console. On the Transcode page, find the ID of the transcoding template group that you want to use.
UserData String No null

The custom settings. The value is a JSON string, which supports configurations such as callbacks. For more information, see UserData.

WorkflowId String No 637adc2b7ba*****51a83d841606f8

The ID of the workflow.

RegisterMetadata

The following table describes the metadata of the media file that you want to register.

Parameter

Type

Required

Description

FileURL

String

Yes

The OSS URL of the media file. The URL can be up to 1,024 bytes in length. The file name must be globally unique. If a file name is repeatedly registered, the unique media ID that is associated with the file name is returned.

Title

String

Yes

The title of the media file. The title can be up to 128 bytes in length. It is encoded in UTF-8.

Description

String

No

The description of the media file. The URL can be up to 1,024 bytes in length. It is encoded in UTF-8.

Tags

String

No

The tag of the media file. A tag can be up to 32 bytes in length, and a maximum of 16 tags can be specified. Separate multiple tags with commas (,). It is encoded in UTF-8.

CoverURL

String

No

The URL of the thumbnail. The URL can be up to 1,024 bytes in length.

CateId

Long

No

The ID of the category.

Response parameters

Parameter Type Example Description
FailedFileURLs List ["http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"]

The URL list of media files failed to be registered.

RegisteredMediaList Array of RegisteredMedia

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

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

The OSS URL of the media file.

MediaId String d97af32828084*****d1896683b1aa38

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

NewRegister Boolean false

Indicates whether the media file is newly registered or has been registered before. Valid values:

  • true: The media file is newly registered.
  • false: The media file has been registered before.
RequestId String 14F43C5C-8033-4*****48B-AD04F64E5098

The ID of the request.

Examples

Sample requests

https://vod.{ApiRegion}.aliyuncs.com/?Action=RegisterMedia
&RegisterMetadatas={"FileURL":"https://bucketName.oss-cn-shanghai.aliyuncs.com/video/test/video.m3u8","Title":"VideoName"}
&<Common request parameters>

Sample success responses

XML format 

<RegisterMediaResponse>
      <RequestId>14F43C5C-8033-43E7-B48B-AD04F64E5098</RequestId>
      <RegisteredMediaList>
            <MediaId>d97af328280842229aed1896683b1aa38</MediaId>
            <FileURL>http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4</FileURL>
            <NewRegister>true</NewRegister>
      </RegisteredMediaList>
      <RegisteredMediaList>
            <MediaId>d97af328280842229aed1896683b1aa38</MediaId>
            <FileURL>http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_02.mp4</FileURL>
            <NewRegister>false</NewRegister>
      </RegisteredMediaList>
      <FailedFileURLs>http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4</FailedFileURLs>
</RegisterMediaResponse>

JSON format 

{
 "RequestId":"14F43C5C-8033-43E7-B48B-AD04F64E5098",
 "RegisteredMediaList": [
      {
     "MediaId":"d97af328280842229aed1896683b1aa38",
     "FileURL":"http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4",
     "NewRegister":true
      },
    {
     "MediaId":"d97af328280842229aed1896683b1aa38",
     "FileURL":"http://*****.oss-cn-shanghai.aliyuncs.com/vod_sample_02.mp4",
     "NewRegister":false
      }
  ],
   "FailedFileURLs":[
      "http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"
  ]
}

Error codes

For a list of error codes, visit the API Error Center.