All Products
Search
Document Center

Intelligent Media Management:CreateMediaConvertTask

Last Updated:Dec 11, 2024

Creates an asynchronous media transcoding task to provide audio and video file processing abilities, such as media transcoding, media splicing, video frame capturing, and video to GIF conversion.

Operation description

  • Before you call this operation, make sure that you are familiar with the billing of Intelligent Media Management (IMM).****

  • Make sure that the specified project exists in the current region. For more information, see Project management.

    **

    Note Asynchronous processing does not guarantee timely task completion.

  • By default, only one type of video, audio, and subtitle streams is processed when you call this operation to process media transcoding. However, you can specify the number of video, audio, or subtitle streams that you want to process.

  • When you use this operation to execute a media merging task, up to 11 media files are supported. In this case, the parameters that involve media transcoding and frame capturing apply to the merged media data.

  • This operation is an asynchronous operation. After a task is executed, the task information is retained only for seven days and cannot be retrieved when the retention period elapses. You can call the GetTask or ListTasks operation to query information about the task.`` If you specify Notification , you can obtain information about the task based on notifications.

    **


Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

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
imm:CreateMediaConvertTaskcreate
*Project
acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
ProjectNamestringYes

The name of the project. You can obtain the name of the project from the response of the CreateProject operation.

immtest
Sourcesarray<object>Yes

The source media files. If multiple files exist at the same time, the Concat feature is enabled. The video files are concatenated in the order of their URI inputs.

objectYes

The source media file.

URIstringNo

The URI of the Object Storage Service (OSS) bucket. Specify the value in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that resides in the same region with the current project. ${Object} specifies the complete path to the file whose name contains an extension.

oss://test-bucket/test-object
StartTimedoubleNo

The start time of the media transcoding task. Unit: seconds. Valid values:

  • 0 (default): starts transcoding when the media starts playing.
  • n: starts transcoding n seconds after the media starts playing. n must be greater than 0.
0
DurationdoubleNo

The transcoding duration of the media. Unit: seconds. Default value: 0. A value of 0 specifies that the transcoding duration lasts until the end of the video.

0
Subtitlesarray<object>No

The subtitles. By default, this parameter is left empty.

objectNo

The subtitle.

URIstringNo

The URI of the Object Storage Service (OSS) bucket. Specify the value in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that resides in the same region with the current project. ${Object} specifies the complete path to the file whose name contains an extension. The following subtitle formats are supported: srt, vtt, mov_text, ass, dvd_sub, and pgs.

oss://test-bucket/subtitles
TimeOffsetdoubleNo

The time offset of the subtitle. Unit: seconds. Default value: 0.

10.5
LanguagestringNo

The subtitle language. If you specify this parameter, comply with the ISO 639-2 standard. This parameter is left empty by default.

eng
Targetsarray<object>Yes

The media processing tasks. You can specify multiple values for this parameter.

objectYes

The media processing task.

URIstringNo

The URI of the OSS bucket in which you want to store the media transcoding output file.

Specify the value in the oss://${Bucket}/${Object} format. ${Bucket} specifies the name of the OSS bucket that resides in the same region with the current project. ${Object} specifies the complete path to the file whose name contains an extension.

  • If the value of URI contains an extension, the endpoint of the OSS bucket matches the URI. If multiple media transcoding output files exist, the endpoints of the correspodning OSS buckets may be overwritten.****

  • If the value of URI does not contain an extension, the endpoint of the OSS bucket consists of the following parameters: URI, Container, and Segment. In the following examples, the value of URI is oss://examplebucket/outputVideo.

    • If the value of Container is mp4 and the value of Segment is null, the endpoint of the OSS bucket is oss://examplebucket/outputVideo.mp4.
    • If the value of Container is ts and the value of Format in Segment is hls, the endpoint of the OSS bucket is oss://examplebucket/outputVideo.m3u8. In addition, multiple ts files prefixed with oss://examplebucket/outputVideo are generated.
oss://test-bucket/targets
ContainerstringNo

The type of the media container.

  • Valid values for audio and video containers: mp4, mkv, mov, asf, avi, mxf, ts, and flv.

  • Valid values only for audio containers: mp3, aac, flac, oga, ac3, and opus.

    **

    Note Specify Container and URI at the same time. If you want to extract subtitles, capture frames, capture image sprites, or rotate media images, set Container and URI to null. In this case, Segment, Video, Audio, and Speed do not take effect.

mp4
SpeedfloatNo

The playback speed of the media. Valid values: 0.5 to 2. Default value: 1.0.

Note This parameter specifies the ratio of the non-regular playback speed of the transcoded media file to the default playback speed of the source media file.
1.0
SegmentobjectNo

The media segmentation settings. By default, no segmentation is performed.

FormatstringNo

The media segmentation mode. Valid values:

  • hls
  • dash
hls
DurationdoubleNo

The duration of the segment. Unit: seconds.

30
StartNumberintegerNo

The start sequence number. You can specify this parameter only if you set Format to hls. Default value: 0.

5
VideoTargetVideoNo

The video processing settings.

Note If you leave Video empty and the first video stream exists, the first video stream is directly copied to the output file.
AudioTargetAudioNo

The audio processing settings.

Note If you leave Audio empty and the first audio stream exists, the first audio stream is directly copied to the output file.
SubtitleTargetSubtitleNo

The subtitle processing settings.

Note If you leave Subtitle empty and the first subtitle stream exists, the first subtitle stream is directly copied to the output file.
ImageTargetImageNo

The frame capturing, sprite capturing, and media rotation settings.

StripMetadatabooleanNo

Specifies whether to remove the metadata, such as title and album, from the media file. Default value: false.

UserDatastringNo

The custom information, which is returned as asynchronous notifications to facilitate notification management in your system. The maximum information length is 2,048 bytes.

{"ID": "user1","Name": "test-user1","Avatar": "http://example.com?id=user1"}
TagsobjectNo

The custom tags. You can search for or filter asynchronous tasks by custom tag.

{"test":"val1"}
CredentialConfigCredentialConfigNo

If you have no special requirements, leave this parameter empty.

The authorization chain. For more information, see Use authorization chains to access resources of other entities.

NotificationNotificationNo

The notification settings. For more information, see "Notification". For information about the asynchronous notification format, see Asynchronous notification format.

AlignmentIndexintegerNo

The sequence number of the main media file in the concatenation list of media files. The main media file provides the default transcoding settings, such as the resolution and the frame rate, for videos and audios. Default value: 0. A value of 0 specifies that the main media file is aligned with the first media file in the concatenation list.

Response parameters

ParameterTypeDescriptionExample
object

The response parameters.

RequestIdstring

The request ID.

CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6
EventIdstring

The event ID.

0ED-1Bz8z71k5TtsUejT4UJ16Es****
TaskIdstring

The task ID.

MediaConvert-adb1ee28-c4c9-42a7-9f54-3b8eadcb****

Examples

Sample success responses

JSONformat

{
  "RequestId": "CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6",
  "EventId": "0ED-1Bz8z71k5TtsUejT4UJ16Es****",
  "TaskId": "MediaConvert-adb1ee28-c4c9-42a7-9f54-3b8eadcb****"
}

Error codes

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

Change history

Change timeSummary of changesOperation
2023-05-09The request parameters of the API has changedView Change Details
2023-04-03The request parameters of the API has changedView Change Details
2023-03-09The request parameters of the API has changedView Change Details
2022-08-16The request parameters of the API has changedView Change Details
2022-08-16The request parameters of the API has changedView Change Details