CreateMediaConvertTask-阿里云帮助中心

Create an asynchronous media transcoding task. This task processes audio and video files for media transcoding, media concatenation, video frame capture, and animated GIF generation.

Operation description

Before you call this operation, ensure you understand the billing methods and pricing for Intelligent Media Management.
Before calling this operation, ensure a project is available in the current region. For more information, see Project Management.
Important The completion time of an asynchronous task is not guaranteed.
When you use this operation for media transcoding, it processes only one video, audio, or subtitle stream by default. You can also configure the number of streams to process.
When you use this operation for media concatenation, you can specify a maximum of 11 media files. Parameters for operations such as media transcoding and frame capture apply to the final concatenated output.
This operation is asynchronous. After a task starts, its information is retained for only 7 days. After this period, you cannot retrieve it. To view task information, call the GetTask or ListTasks operation with the returned TaskId. You can also set the Notification parameter to receive task information via message notifications.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

imm:CreateMediaConvertTask

create

*Project

acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}

None

Request parameters

Parameter	Type	Required	Description	Example
ProjectName	string	Yes	The name of the project. For more information about how to obtain the project name, see Create a project.	test-project
Sources	array<object>	Yes	A list of media files. If you provide more than one file, they are concatenated in the order of their URIs.
	array<object>	No	The source media file.
URI	string	No	The OSS URI of the object. The URI must use the `oss://${Bucket}/${Object}` format, where `${Bucket}` is the name of an OSS bucket in the same region as the project, and `${Object}` is the full path to the object, including its file extension.	oss://test-bucket/test-object
StartTime	number	No	The start time of media transcoding, in seconds. Valid values include: 0 (default): Transcoding starts from the beginning of the media file. n (a value greater than 0): Transcoding starts n seconds into the media file.	0
Duration	number	No	The duration of media transcoding in seconds. The default value, 0, transcodes the media until its end.	0
Subtitles	array<object>	No	A list of subtitles to add.
	object	No	The subtitle settings.
URI	string	No	The OSS URI of the object. The URI must use the `oss://${Bucket}/${Object}` format, where `${Bucket}` is the name of an OSS bucket in the same region as the project, and `${Object}` is the full path to the object, including its file extension. Supported subtitle formats include: srt, vtt, mov_text, ass, dvd_sub, and pgs.	oss://test-bucket/test-object
TimeOffset	number	No	The subtitle delay, in seconds. The default value is 0.	10.5
Language	string	No	The language of the subtitle. The value must comply with the ISO 639-2 standard.	eng
Attached	boolean	No	If true, adds the current source media file to the output as a synchronized audio stream or video stream. The default is false. Note You cannot set Attached to true for the source media file referenced by AlignmentIndex.	false
AlignMode	string	No	The alignment mode for the added audio and video streams. Valid values include: false (default): No alignment is performed. loop: Aligns content by looping the audio or video. pad: Aligns content by padding with silent frames or black frames. Note This parameter only takes effect if Attached is set to true.	false
DisableVideo	boolean	No	Specifies whether to disable the video from the source media file. Valid values include: true: Disables the video. false (default): Includes the video.	false
DisableAudio	boolean	No	Specifies whether to disable the audio from the source media file. Valid values include: true: Disables the audio. false (default): Includes the audio.	false
Targets	array<object>	No	A list of media processing tasks.
	array<object>	No	The settings for an output media file.
URI	string	No	The OSS URI of the output file for media transcoding. The URI must be in the `oss://${Bucket}/${Object}` format. In this format, `${Bucket}` is the name of the OSS bucket, which must be in the same region as the project, and `${Object}` is the full path to the object, including the file extension. If the URI has a file extension, all output media files are saved to this URI. If multiple files are generated, they will overwrite each other. If the URI does not have a file extension, the final output URI is generated based on the URI, Container, and Segment parameters. For example, if the URI is `oss://examplebucket/outputVideo`: If Container is `mp4` and Segment is empty, the OSS URI of the generated media file is `oss://examplebucket/outputVideo.mp4`. If Container is `ts` and Format in Segment is `hls`, the process generates an m3u8 file with the OSS URI `oss://examplebucket/outputVideo.m3u8` and multiple TS files prefixed with `oss://examplebucket/outputVideo`.	oss://test-bucket/test-target-object.mp4
Container	string	No	The media container type. Valid container types include: Audio/video containers: mp4, mkv, mov, asf, avi, mxf, ts, flv Audio-only containers: mp3, aac, flac, oga, ac3, opus Important The `Container` and `URI` parameters must be set together. To perform only subtitle extraction, frame capture, sprite generation, or animated image generation, leave both `Container` and `URI` empty. In this case, parameters such as `Segment`, `Video`, `Audio`, and `Speed` are ignored.	mp4
Speed	number	No	The playback speed of the output media. The value must be between 0.5 and 1.0, inclusive. The default value is 1.0. Note This parameter specifies the default playback speed of the output file as a ratio of the source file's speed. It does not perform speed-up transcoding.	1.0
Segment	object	No	Settings for media segmentation.
Format	string	No	The segmentation method. Valid values include: hls dash	hls
Duration	number	No	The duration of each segment, in seconds.	30
StartNumber	integer	No	The starting sequence number. This parameter is supported only for HLS. The default value is 0.	5
Video	TargetVideo	No	The video processing parameters. Important If this parameter is left empty, the first video stream, if it exists, is copied directly to the output file.
Audio	TargetAudio	No	The audio processing parameters. Important If this parameter is left empty, the first audio stream, if it exists, is copied directly to the output file.
Subtitle	TargetSubtitle	No	The subtitle processing parameters. Important If this parameter is left empty, the first subtitle stream, if it exists, is copied directly to the output file.
Image	TargetImage	No	The parameters for frame capture, sprite generation, and animated image generation.
StripMetadata	boolean	No	If true, removes metadata such as `title` and `album` from the media file. The default is false.
Data	object	No	Settings for retaining data streams. Important Retaining data streams is supported only when the `Container` parameter is set to `mp4`.
Stream	array	No	A list of indexes of the data streams in the source file to process. An empty list (default) indicates that no data streams are retained. An index of -1 indicates that all data streams are retained. Example: `[0,1]` processes the data streams with index 0 and 1; `[1]` processes the data stream with index 1; `[-1]` processes all data streams. Note If a specified index does not correspond to an existing data stream, it is ignored.
	integer	No	The index of the data stream to process.	0
AttachedPicture	object	No	Settings for retaining attached pictures. Important Retaining attached pictures is supported only when the `Container` parameter is set to `mp4` or `mkv`.
Stream	array	No	A list of indexes of the attached pictures in the source file to process. An empty list (default) indicates that no attached pictures are retained. An index of -1 indicates that all attached pictures are retained. Example: `[0,1]` processes the attached pictures with index 0 and 1; `[1]` processes the attached picture with index 1; `[-1]` processes all attached pictures. Note If a specified index does not correspond to an existing attached picture, it is ignored.
	integer	No	The index of the attached picture to process.	0
UserData	string	No	The custom user data. This data is returned in the asynchronous notification, allowing you to associate the notification with your internal system. The maximum length is 2,048 bytes.	{"ID": "testuid","Name": "test-user","Avatar": "http://test.com/testuid"}
Tags	object	No	Custom tags for searching and filtering asynchronous tasks.	{"test":"val1"}
CredentialConfig	CredentialConfig	No	You can leave this parameter empty if you do not have special requirements. The chained authorization configuration. For more information, see Use chained authorization to access resources of other entities.
Notification	Notification	No	The message notification settings. For more information, click Notification. For information about the format of asynchronous notifications, see Asynchronous notification format.
AlignmentIndex	integer	No	When concatenating media files, this specifies the index of the primary file in the Sources list. The default transcoding parameters (such as resolution and frame rate from the `Video` and `Audio` objects) are taken from this primary file. The default index is 0.	0
TargetGroups	array<object>	No	A list of media packaging tasks to convert and package the input media into HLS outputs. Each TargetGroup corresponds to one HLS master playlist.
	array<object>	No
URI	string	No	The OSS URI of the output HLS master playlist file for the packaging task.	oss://test-bucket/test-object/master.m3u8
Targets	array<object>	No	A list of media packaging subtasks. Each `Target` corresponds to a variant stream (`#EXT-X-STREAM-INF`) in the HLS master playlist and generates a corresponding HLS media playlist.
	array<object>	No
URI	string	No	The OSS URI of the output HLS media playlist file for the subtask. Important This URI must be in the same directory as or a subdirectory of `TargetGroups.URI`.	oss://test-bucket/test-target-object.mp4
Container	string	No	The packaging container type. Only `mp4` and `ts` are supported.	mp4
Speed	number	No	The playback speed of the output media. The value must be between 0.5 and 1.0, inclusive. The default value is 1.0. Note This parameter specifies the default playback speed of the output file as a ratio of the source file's speed. It does not perform speed-up transcoding.	1.0
Segment	object	No	The media packaging settings.
Format	string	No	The media packaging format. Only `hls` is supported.	hls
Duration	number	No	The duration of each segment, in seconds.	30
StartNumber	integer	No	The starting sequence number for segments. The default is 0.	5
Video	TargetVideo	No	The video processing parameters. Important If this parameter is left empty, the first video stream, if it exists, is copied directly to the output file.
Audio	TargetAudio	No	The audio processing parameters. Important If this parameter is left empty, the first audio stream, if it exists, is copied directly to the output file.
Subtitle	TargetSubtitle	No	The subtitle processing parameters. Important You must use the `Subtitle.ExtractSubtitle` parameter to package subtitle streams. The `URI` in `Subtitle.ExtractSubtitle` must be in the same directory as or a subdirectory of `TargetGroups.URI`. The `Format` in `Subtitle.ExtractSubtitle` must be `vtt`. You only need to configure this parameter in one `Target` to package all subtitle streams.
StripMetadata	boolean	No	If true, removes metadata from the output file. The default is false.

Response elements

Element	Type	Description	Example
	object	The response body.
RequestId	string	The ID of the request.	CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6
EventId	string	The ID of the event.	0ED-1Bz8z71k5TtsUejT4UJ16Es****
TaskId	string	The ID of the task.	MediaConvert-adb1ee28-c4c9-42a7-9f54-3b8eadcb****

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.