Use CreateMediaConvertTask to create an asynchronous media processing task - Intelligent Media Management

Create an asynchronous media transcoding job. This job supports media transcoding, media concatenation, video frame capturing, and animated image generation.

Operation description

Before using this API, ensure you understand the pricing model and price for Intelligent Media Management.
Before calling this API, ensure an available Project exists in the current region. For more information, see Project Management.
Important Completion times for asynchronous tasks are not guaranteed.
By default, this API processes only a single video, audio, or subtitle stream for media transcoding. You can configure the number of streams.
For media concatenation, this API supports up to 11 media files. The configured parameters for media transcoding, frame capture, and other operations apply to the concatenated media.
This is an asynchronous API. Task information is retained for only 7 days after a task starts and cannot be retrieved afterward. Use the TaskId returned by GetTask or ListTasks to view task information. Alternatively, you can set the Notification parameter to receive task 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. To obtain the project name, see Create a project.	test-project
Sources	array<object>	Yes	A list of source media files. If you provide more than one file, they are concatenated in the order of their URIs.
	array<object>	No	A source media file.
URI	string	No	The OSS URI of the source file. The URI must be in 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 of the object, including the file extension.	oss://test-bucket/test-object
StartTime	number	No	The start time for transcoding, in seconds. Valid values: `0` (default): Starts transcoding at the beginning of the media file. `n` (a value greater than 0): Starts transcoding `n` seconds into the media file.	0
Duration	number	No	The duration of the media to transcode, in seconds. A value of `0` (the default) means transcoding continues to the end of the file.	0
Subtitles	array<object>	No	A list of subtitles to add. This parameter is empty by default.
	object	No	The subtitle information.
URI	string	No	The OSS URI of the subtitle file. The URI must be in 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 of the object, including the 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 time offset, in seconds. Default value: `0`.	10.5
Language	string	No	The language of the subtitles, specified as an ISO 639-2 language code. This parameter is empty by default.	eng
Attached	boolean	No	If `true`, this source media file is added to the output as a synchronized audio or video stream. Default: `false`. Note You cannot set `Attached` to `true` for the source file that is used as the alignment reference (specified by `AlignmentIndex`).	false
AlignMode	string	No	The alignment policy for added audio and video streams. Valid values: `false` (default): No alignment. `loop`: Loops the audio or video content to align the duration. `pad`: Pads the stream with silence (for audio) or black frames (for video) to match the duration. Note This parameter is valid only when `Attached` is set to `true`.	false
DisableVideo	boolean	No	If `true`, disables the video stream from this source. Default: `false`. true: Disabled. false (default): Enabled.	false
DisableAudio	boolean	No	If `true`, disables the audio stream from this source. Default: `false`. true: Disabled. false (default): Enabled.	false
Targets	array<object>	Yes	A list of media processing jobs. You can configure multiple jobs.
	array<object>	No	Defines a single media processing job and its output.
URI	string	No	The OSS URI of the transcoded output file. The URI must be in 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 of the object. If the URI includes 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 include a file extension, the output URI is determined by the URI, Container, and Segment parameters. For example, if the URI is `oss://examplebucket/outputVideo`: If Container is `mp4` and Segment is not set, the output file is saved to `oss://examplebucket/outputVideo.mp4`. If Container is `ts` and `Format` in Segment is `hls`, an M3U8 file is generated at `oss://examplebucket/outputVideo.m3u8`, along with multiple TS files that have the `oss://examplebucket/outputVideo` prefix.	oss://test-bucket/test-target-object.mp4
Container	string	No	The media container for the output file. Supported containers include: Audio/video containers: `mp4`, `mkv`, `mov`, `asf`, `avi`, `mxf`, `ts`, `flv` Audio-only containers: `mp3`, `aac`, `flac`, `oga`, `ac3`, `opus` Important `Container` and `URI` must be specified together. To perform tasks like subtitle extraction, frame capture, or animated image generation, omit both `Container` and `URI`. When these parameters are omitted, no media container is created, and `Segment`, `Video`, `Audio`, and `Speed` are ignored.	mp4
Speed	number	No	The playback speed setting for the output media. Valid values: [0.5, 1.0]. Default value: `1.0`. Note This parameter sets a metadata flag for playback speed; it does not re-encode the media to a different speed (a process known as speed transcoding).	1.0
Segment	object	No	The settings for media segmenting. By default, media segmenting is disabled.
Format	string	No	The media segmenting method. Valid values: `hls` `dash`	hls
Duration	number	No	The duration of each segment, in seconds.	30
StartNumber	integer	No	The starting sequence number for the segments. This parameter is valid only for HLS. Default value: `0`.	5
Video	TargetVideo	No	The video processing parameters. Important If this parameter is omitted, the first video stream is passed through to the output without transcoding.
Audio	TargetAudio	No	The audio processing parameters. Important If this parameter is omitted, the first audio stream is passed through to the output without transcoding.
Subtitle	TargetSubtitle	No	The subtitle processing parameters. Important If this parameter is omitted, the first subtitle stream is passed through to the output.
Image	TargetImage	No	The configuration for frame capture, sprite sheet capture, and animated image generation.
StripMetadata	boolean	No	If `true`, removes metadata (such as `title` and `album`) from the output file. Default: `false`.
Data	object	No
Stream	array	No
	integer	No
AttachedPicture	object	No
Stream	array	No
	integer	No
UserData	string	No	Custom data that is returned in the asynchronous notification. You can use this to associate the notification with your business logic. Maximum length: 2,048 bytes.	{"ID": "testuid","Name": "test-user","Avatar": "http://test.com/testuid"}
Tags	object	No	Custom tags that can be used to search for and filter asynchronous jobs.	{"test":"val1"}
CredentialConfig	CredentialConfig	No	This parameter is optional and only needed for advanced access control scenarios. The configuration for role chaining. For more information, see Use role chaining to access resources of another entity.
Notification	Notification	No	The configuration for asynchronous notifications. For more information about this object, see the Notification data type. For the format of asynchronous notification messages, see Asynchronous notification message format.
AlignmentIndex	integer	No	When concatenating media files, this parameter specifies the index of the primary media file in the list. The primary file provides the default transcoding parameters (such as resolution and frame rate) from its `Video` and `Audio` streams. The default value is `0`, which corresponds to the first media file in the `Sources` list.	0

Response elements

Element	Type	Description	Example
	object	The response object.
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.