CreateMediaConvertTask - Intelligent Media Management - Alibaba Cloud Documentation Center

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.

Debug

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.

Operation	Access level	Resource type	Condition key	Associated operation
imm:CreateMediaConvertTask	create	*Project `acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}`	none	none

Request parameters

Parameter	Type	Required	Description	Example
ProjectName	string	Yes	The name of the project. You can obtain the name of the project from the response of the CreateProject operation.	immtest
Sources	array<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.
	object	Yes	The source media file.
URI	string	No	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
StartTime	double	No	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
Duration	double	No	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
Subtitles	array<object>	No	The subtitles. By default, this parameter is left empty.
	object	No	The subtitle.
URI	string	No	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
TimeOffset	double	No	The time offset of the subtitle. Unit: seconds. Default value: 0.	10.5
Language	string	No	The subtitle language. If you specify this parameter, comply with the ISO 639-2 standard. This parameter is left empty by default.	eng
Targets	array<object>	Yes	The media processing tasks. You can specify multiple values for this parameter.
	object	Yes	The media processing task.
URI	string	No	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
Container	string	No	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
Speed	float	No	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
Segment	object	No	The media segmentation settings. By default, no segmentation is performed.
Format	string	No	The media segmentation mode. Valid values: hls dash	hls
Duration	double	No	The duration of the segment. Unit: seconds.	30
StartNumber	integer	No	The start sequence number. You can specify this parameter only if you set Format to hls. Default value: 0.	5
Video	TargetVideo	No	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.
Audio	TargetAudio	No	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.
Subtitle	TargetSubtitle	No	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.
Image	TargetImage	No	The frame capturing, sprite capturing, and media rotation settings.
StripMetadata	boolean	No	Specifies whether to remove the metadata, such as `title` and `album`, from the media file. Default value: false.
UserData	string	No	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"}
Tags	object	No	The custom tags. You can search for or filter asynchronous tasks by custom tag.	{"test":"val1"}
CredentialConfig	CredentialConfig	No	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.
Notification	Notification	No	The notification settings. For more information, see "Notification". For information about the asynchronous notification format, see Asynchronous notification format.
AlignmentIndex	integer	No	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

Parameter	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6
EventId	string	The event ID.	0ED-1Bz8z71k5TtsUejT4UJ16Es****
TaskId	string	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 time	Summary of changes	Operation
2023-05-09	The request parameters of the API has changed	View Change Details
2023-04-03	The request parameters of the API has changed	View Change Details
2023-03-09	The request parameters of the API has changed	View Change Details
2022-08-16	The request parameters of the API has changed	View Change Details
2022-08-16	The request parameters of the API has changed	View Change Details