ListTranscodeJobs - Intelligent Media Services - Alibaba Cloud Documentation Center

Lists the transcoding jobs for a media file.

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

ice:ListTranscodeJobs

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
StartOfCreateTime	string	No	The start of the time range to filter jobs by their creation time. The time must be in UTC and formatted as `yyyy-MM-ddTHH:mm:ssZ`.	2022-07-01T00:00:00Z
EndOfCreateTime	string	No	The end of the time range to filter jobs by their creation time. The time must be in UTC and formatted as `yyyy-MM-ddTHH:mm:ssZ`.	2022-07-15T00:00:00Z
ParentJobId	string	No	Filters by job ID.	7b38a5d86f1e47838927b6e7ccb1****
Status	string	No	The job status. Valid values: `Init`: Submitted. `Success`: Succeeded. `Fail`: Failed.	Success
OrderBy	string	No	The sort order. Valid values: `CreateTimeDesc`: Sorts by creation time in descending order. `CreateTimeAsc`: Sorts by creation time in ascending order.	CreateTimeDesc
PageSize	integer	No	The number of entries per page. Valid values: 1-100. Default: 20.	10
NextPageToken	string	No	The token for the next page of results. Not required for the first page.	ab4802364a2e49208c99efab82df****

Response elements

Element	Type	Description	Example
	object
RequestId	string	The ID of the request.	31E30781-9495-5E2D-A84D-759B0A01E262
Jobs	array<object>	The list of jobs.
	array<object>	The job details.
CreateTime	string	The time when the job was created. The time is in the `yyyy-MM-ddTHH:mm:ssZ` format. The time is displayed in UTC.	2022-01-12T08:49:41Z
Name	string	The job name.	transcode-job
RequestId	string	The request ID of the job.	31E30781-9495-5E2D-A84D-759B0A01E262
ParentJobId	string	The parent job ID.	8b2198504dd340b7b3c9842a74fc****
JobCount	integer	The number of sub-jobs.	1
Status	string	The status of the job. Valid values: `Success`: The job is successful if at least one sub-job is successful. `Fail`: The job fails if all sub-jobs fail.	Success
TriggerSource	string	The source of the job. Valid values: `API`: The job is submitted by calling an API operation. `Workflow`: The job is triggered by a workflow. `Console`: The job is submitted on the console.	API
Percent	integer	The progress of the job.	0
SubmitTime	string	The time when the job was submitted. The time is in the `yyyy-MM-ddTHH:mm:ssZ` format. The time is displayed in UTC.	2022-01-12T08:49:41Z
FinishTime	string	The time when the job was complete. The time is in the `yyyy-MM-ddTHH:mm:ssZ` format. The time is displayed in UTC.	2022-01-12T08:49:41Z
InputGroup	array<object>	The input group of the job. A single input indicates a transcoding job. Multiple inputs indicate a composition job.
	object	The job input.
Type	string	The type of the media asset. Valid values: `OSS`: an OSS file. `Media`: a media asset ID.	OSS
Media	string	The media information. The value of this parameter varies based on the value of Type. If Type is set to `OSS`, the value of this parameter must be an OSS URL. Both the `oss://` and `http(s)://` protocols are supported. If Type is set to `Media`, the value of this parameter must be a media ID.	oss://bucket/path/to/video.mp4
InputUrl	string	The URL of the media stream. This parameter is required only when you transcode a media stream.	oss://bucket/path/to/video.mp4
OutputGroup	array<object>	The output group of the job.
	array<object>	The job output.
Output	object	The output media configuration.
Type	string	The type of the media asset. Valid values: `OSS`: an OSS file. `Media`: a media asset ID.	OSS
Media	string	The media information. The value of this parameter varies based on the value of Type. If Type is set to `OSS`, the value of this parameter must be an OSS URL. Both the `oss://` and `http(s)://` protocols are supported. If Type is set to `Media`, the value of this parameter must be a media ID.	oss://bucket/path/to/video.mp4
OutputUrl	string	The URL of the output stream. This parameter is required only when you transcode a media stream.	oss://bucket/path/to/{MediaId}/{JobId}.mp4
ProcessConfig	object	The job processing configuration.
Transcode	object	The transcoding configuration.
TemplateId	string	The template ID.	9547c6ad97cb4f2aaa29683ebd18****
OverwriteParams	object	The override parameter. If you specify this parameter, the corresponding parameter in the template is overwritten.
Video	object	The video settings.
Codec	string	The video codec.	H.264
Profile	string	The encoding profile. Valid values include baseline, main, and high. `baseline`: suitable for mobile devices. `main`: suitable for standard-definition devices. `high`: suitable for high-definition devices. Default value: `high`.	Main
Bitrate	string	The average video bitrate. Valid values: 10 to 50000. Unit: Kbit/s.	3000
Crf	string	The quality-to-bitrate control factor. Valid values: 0 to 51. Default value: If the codec is H.264, the default value is 23. If the codec is H.265, the default value is 26. If you specify Crf, the value of Bitrate is ignored.	23
Width	string	The width. Valid values: 128 to 4096. Unit: px. Default value: the width of the source video.	1920
Height	string	The height. Valid values: 128 to 4096. Unit: px. Default value: the height of the source video.	1080
Fps	string	The frame rate. Valid values: 0 to 60. If the frame rate of the input file is greater than 60, the value is 60. Default value: the frame rate of the input file.	25
Gop	string	The maximum number of frames in a Group of Pictures (GOP). Valid values: 1 to 1080000. Default value: 250.	250
Preset	string	The preset of the video encoder. This parameter is supported only when the video codec is H.264. Valid values: `veryfast`, `fast`, `medium`, `slow`, and `slower`. Default value: `medium`.	medium
ScanMode	string	The scan mode. Valid values: `interlaced` and `progressive`.	progressive
PixFmt	string	The pixel format. Valid values include `yuv420p` and `yuvj420p`.	yuv420p
Remove	string	Specifies whether to delete the video. Valid values: `true` and `false`.	false
Crop	string	The cropping settings. Two modes are supported. Automatic: Set the value to `border` to automatically detect and crop black borders. Manual: Specify the crop area in the `width:height:left:top` format. Example: `1280:800:0:140`.	1280:800:0:140
Pad	string	The settings for adding black bars. Format: `width:height:left:top`. Example: `1280:800:0:140`.	1280:800:0:140
LongShortMode	string	Specifies whether to enable adaptive resolution by long and short sides.	false
Bufsize	string	The buffer size. Valid values: 1000 to 128000. Default value: 6000. Unit: Kbit.	6000
Maxrate	string	The maximum video bitrate. Valid values: 10 to 50000. Unit: Kbit/s.	9000
AbrMax	string	The maximum bitrate for adaptive bitrate (ABR) streaming. This parameter is valid only for videos with a narrow height and a wide width. Valid values: 10 to 50000. Unit: Kbit/s.	6000
Audio	object	The audio settings.
Codec	string	The audio codec. Valid values: `AAC`, `MP3`, `VORBIS`, and `FLAC`. Default value: `AAC`.	AAC
Profile	string	The audio encoding preset. This parameter is supported only when the audio codec is AAC. Valid values: `aac_low`, `aac_he`, `aac_he_v2`, `aac_ld`, and `aac_eld`.	aac_low
Samplerate	string	The sample rate. Valid values: 22050, 32000, 44100, 48000, and 96000. Default value: 44100. Unit: Hz.	44100
Bitrate	string	The audio bitrate of the output file. Valid values: 8 to 1000. Unit: Kbit/s. Default value: 128.	128
Channels	string	The number of audio channels. Default value: 2.	2
Remove	string	Specifies whether to delete the audio stream. Valid values: `true` and `false`.	false
Volume	object	The volume control settings.
Method	string	The volume adjustment method.	auto
IntegratedLoudnessTarget	string	The target integrated loudness.	-6
TruePeak	string	The true peak level.	-1
LoudnessRangeTarget	string	The target loudness range.	8
Container	object	The container format settings.
Format	string	The container format.	mp4
MuxConfig	object	The muxing settings.
Segment	object	The segment settings.
Duration	string	The duration of each segment.	10
ForceSegTime	string	The time points at which to enforce segmentation.	2,3
Tags	object	The custom tags.
	string	The key-value pairs of custom tags.
ImageWatermarks	array<object>	The image watermark configurations.
	array<object>	The image watermark configuration.
TemplateId	string	The template ID.	9547c6ad97cb4f2aaa29683ebd18****
OverwriteParams	object	The override parameter. If you specify this parameter, the corresponding parameter in the template is overwritten.
Width	string	The width of the watermark.	32
Height	string	The height of the watermark.	32
Dx	string	The horizontal offset of the watermark.	10
Dy	string	The vertical offset of the watermark.	10
ReferPos	string	The reference position. Valid values: `TopLeft`, `TopRight`, `BottomLeft`, and `BottomRight`. Default value: `TopLeft`.	TopLeft
Timeline	object	The timeline settings.
Start	string	The start time.	00:00:05
Duration	string	The display duration in seconds. You can also set the value to `ToEND`.	ToEND
File	object	The watermark image file.
Type	string	The type of the media asset. Valid values: `OSS`: an OSS file. `Media`: a media asset ID.	OSS
Media	string	The media information. The value of this parameter varies based on the value of Type. If Type is set to `OSS`, the value of this parameter must be an OSS URL. Both the `oss://` and `http(s)://` protocols are supported. If Type is set to `Media`, the value of this parameter must be a media ID.	oss://bucket/path/to/video.mp4
TextWatermarks	array<object>	The text watermark configurations.
	array<object>	The text watermark configuration.
TemplateId	string	The template ID.	9547c6ad97cb4f2aaa29683ebd18****
OverwriteParams	object	The override parameter. If you specify this parameter, the corresponding parameter in the template is overwritten.
Content	string	The watermark text, which must be UTF-8 encoded. The text does not need to be Base64 encoded.	Test Watermark
FontName	string	The font.	SimSun
FontColor	string	The color.	#006400
FontAlpha	string	The transparency.	1.0
Top	string	The distance of the watermark from the top edge.	10
Left	string	The distance from the left edge of the video.	10
FontSize	integer	The font size.	16
BorderWidth	integer	The width of the border.	0
BorderColor	string	The color of the border.	#006400
Adaptive	string	Specifies whether to adjust the font size based on the output video size. `true`: The font size is automatically adjusted based on the output video size. `false`: The font size remains fixed and is not affected by the output video size. Default value: false	false
Subtitles	array<object>	The subtitle burn-in settings.
	array<object>	The subtitle burn-in configuration.
TemplateId	string	The template ID.	9547c6ad97cb4f2aaa29683ebd18****
OverwriteParams	object	The overwrite parameters. If specified, these parameters overwrite the corresponding parameters in the template.
Format	string	The format of the subtitle file.	vtt
CharEnc	string	The file encoding format.	UTF-8
File	object	The subtitle file.
Type	string	The type of the media object. Valid values: OSS: an Object Storage Service (OSS) file. Media: the ID of the Media Asset.	OSS
Media	string	The media value: If type is OSS, the value is a URL. Both OSS and HTTP protocols are supported. If type is Media, the value is the Media Asset ID.	oss://bucket/path/to/video.mp4
Encryption	object	The encryption settings.
EncryptType	string	The encryption type.	PrivateEncryption
CipherText	string	The key ciphertext for standard encryption.	MTYi00NDU0LTg5O****
DecryptKeyUri	string	The URL of the decryption service for standard encryption.	https://sample.com/path?CipherText=MTYi00NDU0LTg5O****
CombineConfigs	array<object>	The configurations for combining multiple inputs.
	object
AudioIndex	string	The audio stream index.	0 or exclude
VideoIndex	string	The index of the video stream.	0 or exclude
Start	number	The start time of the input stream. The default value is 0.	0.0
Duration	number	The duration of the input stream. The default is the duration of the video.	20.0
IsInheritTags	boolean	Specifies whether to inherit tags from the input stream. This parameter applies only when the input is a Media Asset. Default Value: false
UserData	string	The user data.	user-data
ScheduleConfig	object	The schedule configuration of the job.
PipelineId	string	The pipeline ID.	e37ebee5d98b4781897f6086e89f****
Priority	integer	The priority of the job. A larger value indicates a higher priority. The value can be an integer from 1 to 10.	5
NextPageToken	string	The token for the next page of results. Leave this parameter empty for the first request. The token is returned after the first query.	019daf5780f74831b0e1a767c9f1****

Examples

Success response

JSON format

{
  "RequestId": "31E30781-9495-5E2D-A84D-759B0A01E262",
  "Jobs": [
    {
      "CreateTime": "2022-01-12T08:49:41Z",
      "Name": "transcode-job",
      "RequestId": "31E30781-9495-5E2D-A84D-759B0A01E262",
      "ParentJobId": "8b2198504dd340b7b3c9842a74fc****",
      "JobCount": 1,
      "Status": "Success",
      "TriggerSource": "API",
      "Percent": 0,
      "SubmitTime": "2022-01-12T08:49:41Z",
      "FinishTime": "2022-01-12T08:49:41Z",
      "InputGroup": [
        {
          "Type": "OSS",
          "Media": "oss://bucket/path/to/video.mp4",
          "InputUrl": "oss://bucket/path/to/video.mp4"
        }
      ],
      "OutputGroup": [
        {
          "Output": {
            "Type": "OSS",
            "Media": "oss://bucket/path/to/video.mp4",
            "OutputUrl": "oss://bucket/path/to/{MediaId}/{JobId}.mp4"
          },
          "ProcessConfig": {
            "Transcode": {
              "TemplateId": "9547c6ad97cb4f2aaa29683ebd18****",
              "OverwriteParams": {
                "Video": {
                  "Codec": "H.264",
                  "Profile": "Main",
                  "Bitrate": "3000",
                  "Crf": "23",
                  "Width": "1920",
                  "Height": "1080",
                  "Fps": "25",
                  "Gop": "250",
                  "Preset": "medium",
                  "ScanMode": "progressive",
                  "PixFmt": "yuv420p",
                  "Remove": "false",
                  "Crop": "1280:800:0:140",
                  "Pad": "1280:800:0:140",
                  "LongShortMode": "false",
                  "Bufsize": "6000",
                  "Maxrate": "9000",
                  "AbrMax": "6000"
                },
                "Audio": {
                  "Codec": "AAC",
                  "Profile": "aac_low",
                  "Samplerate": "44100",
                  "Bitrate": "128",
                  "Channels": "2",
                  "Remove": "false",
                  "Volume": {
                    "Method": "auto",
                    "IntegratedLoudnessTarget": "-6",
                    "TruePeak": "-1",
                    "LoudnessRangeTarget": "8"
                  }
                },
                "Container": {
                  "Format": "mp4"
                },
                "MuxConfig": {
                  "Segment": {
                    "Duration": "10",
                    "ForceSegTime": "2,3"
                  }
                },
                "Tags": {
                  "key": ""
                }
              }
            },
            "ImageWatermarks": [
              {
                "TemplateId": "9547c6ad97cb4f2aaa29683ebd18****",
                "OverwriteParams": {
                  "Width": "32",
                  "Height": "32",
                  "Dx": "10",
                  "Dy": "10",
                  "ReferPos": "TopLeft",
                  "Timeline": {
                    "Start": "00:00:05",
                    "Duration": "ToEND"
                  },
                  "File": {
                    "Type": "OSS",
                    "Media": "oss://bucket/path/to/video.mp4"
                  }
                }
              }
            ],
            "TextWatermarks": [
              {
                "TemplateId": "9547c6ad97cb4f2aaa29683ebd18****",
                "OverwriteParams": {
                  "Content": "Test Watermark",
                  "FontName": "SimSun",
                  "FontColor": "#006400",
                  "FontAlpha": "1.0",
                  "Top": "10",
                  "Left": "10",
                  "FontSize": 16,
                  "BorderWidth": 0,
                  "BorderColor": "#006400",
                  "Adaptive": "false"
                }
              }
            ],
            "Subtitles": [
              {
                "TemplateId": "9547c6ad97cb4f2aaa29683ebd18****",
                "OverwriteParams": {
                  "Format": "vtt",
                  "CharEnc": "UTF-8",
                  "File": {
                    "Type": "OSS",
                    "Media": "oss://bucket/path/to/video.mp4"
                  }
                }
              }
            ],
            "Encryption": {
              "EncryptType": "PrivateEncryption",
              "CipherText": "MTYi00NDU0LTg5O****",
              "DecryptKeyUri": "https://sample.com/path?CipherText=MTYi00NDU0LTg5O****"
            },
            "CombineConfigs": [
              {
                "AudioIndex": "0 or exclude",
                "VideoIndex": "0 or exclude",
                "Start": 0,
                "Duration": 20
              }
            ],
            "IsInheritTags": false
          }
        }
      ],
      "UserData": "user-data",
      "ScheduleConfig": {
        "PipelineId": "e37ebee5d98b4781897f6086e89f****",
        "Priority": 5
      }
    }
  ],
  "NextPageToken": "019daf5780f74831b0e1a767c9f1****"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.