Help Center/ Media Processing Center/ API Reference/ Transcoding APIs/ Querying Transcoding Tasks

Updated on 2026-02-25 GMT+08:00

Online Debugging

CLI Examples

View PDF

Querying Transcoding Tasks

Function

This API is used to query one or more transcoding tasks.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
mpc:transcodeTask:view	Read	-	-	-	-

URI

GET /v1/{project_id}/transcodings

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
task_id	No	Array of longs	Task ID. A maximum of 10 transcoding task IDs can be queried at a time.
status	No	String	Task execution status Possible options are: WAITING: pending TRANSCODING: executing SUCCEEDED: completed FAILED: failed CANCELED: deleted NEED_TO_BE_AUDIT: pending for review
start_time	No	String	Start time. If task_id is specified, this parameter is invalid. Its format is yyyymmddhhmmss. The value must be a time-zone agnostic UTC time.
end_time	No	String	End time. If task_id is specified, this parameter is invalid. Its format is yyyymmddhhmmss. The value must be a time-zone agnostic UTC time.
page	No	Integer	Page number. If task_id is specified, this parameter is invalid. Default value: 0
size	No	Integer	Number of records on each page. If task_id is specified, this parameter is invalid. The value ranges from 1 to 100. Default value: 10

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
x-language	No	String	Client language.
X-Auth-Token	No	String	User token The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.
Authorization	No	String	Authentication information. This parameter is mandatory when AK/SK-based authentication is used.
X-Project_Id	No	String	Project ID. This parameter is mandatory when AK/SK-based authentication is used. It is same as the project ID in path parameters.
X-Sdk-Date	No	String	Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
task_array	Array of QueryTranscodingsTaskResponse objects	Returned task group details.
is_truncated	Integer	Whether the query results are truncated. Possible values: 1: Query results are truncated. Some results are not returned. You can configure the page and size parameters to continue the query. 0: Query results are not truncated. All results are returned.
total	Integer	Number of records

**Table 5** QueryTranscodingsTaskResponse
Parameter	Type	Description
task_id	String	Task ID
status	String	Task execution status. The options include: NO_TASK: no task WAITING: pending TRANSCODING**: transcoding SUCCEEDED: successful FAILED: failed CANCELED: deleted NEED_TO_BE_AUDIT: pending for review
progress	Integer	Task execution progress, in percentage. The value range is [0, 100]. 0 is returned by default for users not in the whitelist, and a valid value is returned for whitelisted users. If you need to be added to the whitelist, contact technical support.
create_time	String	Task start time
end_time	String	Task end time
trans_template_id	Array of integers	ID of transcoding templates
input	ObsObjInfo object	Storage location of an input file. The information includes the location, bucket name, and path.
output	ObsObjInfo object	Storage location of an output file. The information includes the location, bucket name, and path.
output_file_name	Array of strings	Name of the output file. The value is of the array type and may contain multiple names, including snapshot names.
user_data	String	Custom user data
error_code	String	Status code of a transcoding task
description	String	Task description. If an error occurs in a transcoding task, this field indicates the error cause.
tips	String	Message displayed if the audio sampling rate is too low
transcode_detail	TranscodeDetail object	Output information of snapshots
thumbnail_output	ObsObjInfo object	Output information of snapshots. The information includes the location, bucket name, and path.
thumbnail_outputname	String	Name of the snapshot package
pic_info	Array of PicInfo objects	Snapshot file information
thumbnails_info	Array of ThumbnailsInfo objects	Snapshot file information.
image_sprite_info	Array of ImageSpriteInfo objects	Image sprite information, which is an array. A maximum of 20 members are supported.
av_parameters	Array of AvParameters objects	Transcoding parameter If both trans_template_id and this parameter are configured, this parameter is preferentially used for transcoding.
additional_manifests	Array of AdditionalManifests objects	Customized parameter for the primary index.
metadata	Array of FileMetaData objects	Metadata of the output file.

**Table 6** TranscodeDetail
Parameter	Type	Description
multitask_info	Array of MultiTaskInfo objects	Details about failed transcoding in the case of one-in and multiple-out
input_file	SourceInfo object	Input file information
replace_sub_index	Array of strings	Sub-index file to be replaced

**Table 7** MultiTaskInfo
Parameter	Type	Description
template_id	Integer	Template ID
error	ErrorResponse object	Error message about failed transcoding
output_file	SourceInfo object	Information about a single output

**Table 8** ErrorResponse
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error description

**Table 9** SourceInfo
Parameter	Type	Description
duration	Integer	Duration of an input file Unit: second
duration_ms	Long	Duration of an input file Unit: ms
format	String	File format
size	Long	Size of an input file
manifest_name	String	Independent MPD index file name
md5	String	MD5 value of the video. NOTE: This field is returned only by the transcoding and parsing APIs. By default, this field is disabled. You need to submit a service ticket to enable it.
video_info	VideoInfo object	Video information
audio_info	Array of AudioInfo objects	Audio information

**Table 10** VideoInfo
Parameter	Type	Description
width	Integer	Video width
height	Integer	Video height
bitrate	Integer	Video bitrate. Unit: kbit/s NOTE: On August 7, 2024, the following modification was made on the video parsing API: Before: If sync in a synchronous video parsing task is set to 1, the unit of bitrate in VideoInfo of the response is bit/s. After: In a synchronous video parsing task, the unit of bitrate in VideoInfo of the response is changed to kbit/s. The preceding update may impact your transcoding workloads. Pay attention to the update and adjust your workloads accordingly.
bitrate_bps	Long	Video bitrate Unit: bit/s
frame_rate	Integer	Frame rate. The value is 0 or ranges from 5 to 60. The value 0 indicates adaptive frame rate. Unit: FPS NOTE: If the configured frame rate is not within the value range, the value is automatically changed to 0. If the configured frame rate is higher than the frame rate of the input file, the value is automatically changed to the frame rate of the input file.
codec	String	Video codec
dynamic_range	String	Dynamic range type of an input file. Possible values: SDR HDR10 CUVA_HDR
duration	String	Video stream duration, in seconds. NOTE: This field is returned only by the transcoding and parsing APIs. By default, this field is disabled for the parsing API. You need to submit a service ticket to enable it.
duration_ms	String	Video stream duration, in milliseconds NOTE: This field is returned only by the transcoding and parsing APIs. By default, this field is disabled for the parsing API. You need to submit a service ticket to enable it.
rotate	Float	Video shooting angle, in degrees. NOTE: This field is returned only by the transcoding and parsing APIs. By default, this field is disabled for the parsing API. You need to submit a service ticket to enable it.

**Table 11** AudioInfo
Parameter	Type	Description
codec	String	Audio codec
sample	Integer	Audio sampling rate
channels	Integer	Number of audio channels
bitrate	Integer	Audio bitrate Unit: kbit/s
bitrate_bps	Long	Audio bitrate Unit: bit/s
duration	String	Audio stream duration, in seconds. NOTE: This field is returned only by the transcoding and parsing APIs. By default, this field is disabled for the parsing API. You need to submit a service ticket to enable it.
duration_ms	String	Audio stream duration, in milliseconds. NOTE: This field is returned only by the transcoding and parsing APIs. By default, this field is disabled for the parsing API. You need to submit a service ticket to enable it.

**Table 12** ThumbnailsInfo
Parameter	Type	Description
pic_info	Array of PicInfo objects	Snapshot file information.
output	ObsObjInfo object	Output file information.
output_name	String	Name of the snapshot package.

**Table 13** PicInfo
Parameter	Type	Description
pic_name	String	Snapshot file name

**Table 14** ImageSpriteInfo
Parameter	Type	Description
row_count	Integer	Number of rows of sub-images in the image sprite.
column_count	Integer	Number of columns of sub-images in the image sprite.
total_count	Integer	Number of sub-images in the image sprite.
width	Integer	Width of the sub-images in the image sprite.
height	Integer	Height of the sub-images in the image sprite.
output_image_name	Array of strings	Path of each image sprite.
output_webvtt_name	String	Path of the WebVTT file that describes the mapping between the positions of sub-images in the image sprite and video timestamps. The WebVTT file specifies the timestamps for each sub-image within the image sprite and defines their coordinates. Generally, the WebVTT file is used by players to implement previews.
output	ObsObjInfo object	Output file information.

**Table 15** AvParameters
Parameter	Type	Description
video	VideoParameters object	Video parameters
audio	Audio object	Audio parameters
common	Common object	Common parameters
output	ObsObjInfo object	Output path. If this parameter is not set, the output is stored together with the outer transcoded output. Note: For HLS multiple outputs, if the path of each output is different, index.m3u8 is unavailable, and audio and video separation is unavailable.
output_filename	String	Output file name.

**Table 16** VideoParameters
Parameter	Type	Description
output_policy	String	Output policy: If output_policy is set to discard in video parameters and transcode in audio parameters, only audio is output. If output_policy is set to transcode in video parameters and to discard in audio parameters, only video is output. If output_policy is set to copy in video parameters, the original video is copied without codec. If output_policy is set to copy in audio parameters, the original audio is copied without codec. output_policy cannot be set to discard in video and audio parameters at the same time. If output_policy is set to transcode in video and video parameters at the same time, video and audio are output. The options are as follows: discard transcode copy
codec	Integer	Video codec. Possible values: 1: VIDEO_CODEC_H264 2: VIDEO_CODEC_H265
crf	Object	Factor for controlling the constant video bitrate. The value range is [0, 51].
max_bitrate	Integer	Maximum output bitrate. The value can be 0 or an integer from 40 to 800,000. Unit: kbit/s This field is used when the Constant Rate Factor (CRF) is used. The value is generally set to 1.5 times of the average bitrate of the source file.
bitrate	Integer	Average output bitrate Its value is 0 or an integer ranging from 40 to 50,000. Unit: kbit/s If this parameter is set to 0, the average output bitrate is an adaptive value.
buf_size	Integer	Buffer size. The value can be 0 or an integer from 40 to 800,000. Unit: kbit
profile	Integer	Encoding profile. Possible values: 1: VIDEO_PROFILE_H264_BASE 2: VIDEO_PROFILE_H264_MAIN 3: VIDEO_PROFILE_H264_HIGH 4: VIDEO_PROFILE_H265_MAIN
level	Integer	Encoding level Options: 0: AUTO 1: VIDEO_LEVEL_1_0 2: VIDEO_LEVEL_1_1 3: VIDEO_LEVEL_1_2 4: VIDEO_LEVEL_1_3 5: VIDEO_LEVEL_2_0 6: VIDEO_LEVEL_2_1 7: VIDEO_LEVEL_2_2 8: VIDEO_LEVEL_3_0 9: VIDEO_LEVEL_3_1 10: VIDEO_LEVEL_3_2 11: VIDEO_LEVEL_4_0 12: VIDEO_LEVEL_4_1 13: VIDEO_LEVEL_4_2 14: VIDEO_LEVEL_5_0 15: VIDEO_LEVEL_5_1
preset	Integer	Encoding quality. The options include: 1: VIDEO_PRESET_SPEED (fast encoding) 3: VIDEO_PRESET_HIGHQUALITY (high-quality encoding). 4: VIDEO_PRESET_QUALITY (quality encoding). 5: VIDEO_PRESET_BALANCE (balanced encoding) The default value is 1.
max_iframes_interval	Integer	Maximum I-frame interval. The value ranges from 2 to 10. Default value: 5 Unit: second
bframes_count	Integer	Maximum B-frame interval. Range H.264: The value ranges from 0 to 8. The default value is 4. H.265: The value ranges from 0 to 7. The default value is 7. Unit: frame
frame_rate	Integer	Frame rate. The value is 0 (adaptive) or ranges from 5 to 60. Unit: FPS NOTE: If the configured frame rate is not within the value range, the value is automatically changed to 0. If the configured frame rate is higher than the frame rate of the input file, the value is automatically changed to the frame rate of the input file.
width	Integer	Video width, in pixels H.264: The value is a multiple of 2 from 32 to 4,096. H.265: The value is a multiple of 2 from 320 to 4,096.
height	Integer	Video height, in pixels H.264: The value is a multiple of 2 from 32 to 2,880. H.265: The value is a multiple of 2 from 240 to 2,880.
black_cut	Integer	Whether to enable black bar removal. 0: disables black bar removal 1: enables black bar removal and low-complexity algorithms for videos longer than 5 minutes 2: enables black bar removal and high-complexity algorithms for videos no longer than 5 minutes
stream_name	String	Stream name

**Table 17** Audio
Parameter	Type	Description
output_policy	String	Output policy: If output_policy is set to discard in video parameters and transcode in audio parameters, only audio is output. If output_policy is set to transcode in video parameters and to discard in audio parameters, only video is output. If output_policy is set to copy in video parameters, the original video is copied without codec. If output_policy is set to copy in audio parameters, the original audio is copied without codec. output_policy cannot be set to discard in video and audio parameters at the same time. If output_policy is set to transcode in video and video parameters at the same time, video and audio are output. The options are as follows: discard transcode copy
codec	Integer	Audio codec Possible options are: 1: AAC 2: HEAAC1 3: HEAAC2 4: MP3
sample_rate	Integer	Audio sampling rate The options are as follows: 1: AUDIO_SAMPLE_AUTO 2: AUDIO_SAMPLE_22050 (22,050 Hz) 3: AUDIO_SAMPLE_32000 (32,000 Hz) 4: AUDIO_SAMPLE_44100 (44,100 Hz) 5: AUDIO_SAMPLE_48000 (48,000 Hz) 6: AUDIO_SAMPLE_96000 (96,000 Hz) NOTE: When the encoding format is MP3, the audio sampling ratio cannot be 6.
bitrate	Integer	Audio bitrate. The value is 0 or ranges from 8 to 1,000. Unit: kbit/s
channels	Integer	Number of audio channels Options: 1: AUDIO_CHANNELS_1 (mono) 2: AUDIO_CHANNELS_2 (stereo) 6: AUDIO_CHANNELS_5_1 (5.1 surround sound) When the media packaging format is audio (MP3), the number of audio channels cannot be set to 5.1.

**Table 18** Common
Parameter	Type	Description
PVC	Boolean	Whether to enable low-bitrate HD The options are as follows: false: disabled (This function is disabled by default.) true: enabled (The value 0 indicates that the function is disabled. Other positive integers and negative values indicate true.)
hls_interval	Integer	HLS segment duration. This parameter is used only when pack_type is set to 1 or 3. Value range: [2,10] Unit: second
dash_interval	Integer	DASH segment duration. This parameter is used only when pack_type is set to 2 or 3. Value range: [2,10] Unit: second
pack_type	Integer	Container format. The options include: 1: HLS 2: DASH 3: HLS+DASH 4: MP4 5: MP3 6: ADTS 8: MOV 9: FLV 10: AVI NOTE: If pack_type is set to 5 or 6, do not configure video parameters. If pack_type is set to 9, multi-audio is not supported. If pack_type is set to 10, H.265 encoding is not supported.

**Table 19** ObsObjInfo
Parameter	Type	Description
bucket	String	OBS bucket name
location	String	Region where an OBS bucket is located. It must be the same as the region where MPC is deployed.
object	String	OBS object path, which complies with the OSS Object definition. If this parameter is used for an input, an object must be specified. If this parameter is used for an output, only the directory where the output is to be stored needs to be specified. A subtitle file name that contains special characters (such as [) will cause the transcoding task to fail. Correct example: demo.srt Incorrect example: [demo.srt
file_name	String	File name, which can contain a maximum of 180 characters. If this parameter is specified, the output object name is object/file_name. If this parameter is not specified, the output object name is object/xxx, where xxx is specified by MPC. When it is used as an output file name: This parameter is valid for container format conversion. The output file name must be specified. If the output file name needs to be specified during transcoding, use the parameter output_filenames. This parameter is valid for parsing. If a file name is specified during parsing, the parsing parameters are written to the specified file name and the file metadata is obtained by querying JSON data in the API response. This parameter is invalid for snapshot capturing. This parameter is invalid for conversion into animated GIFs. When the output file is in HLS format, a file name containing index, such as index.m3u8, will cause playback failure.

**Table 20** AdditionalManifests
Parameter	Type	Description
manifest_name_modifier	String	Customized index file name extension
selected_outputs	Array of strings	Name of the selected stream

**Table 21** FileMetaData
Parameter	Type	Description
name	String	Metadata name.
value	String	Metadata value.

Status code: 400

**Table 22** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error description

Example Requests

GET https://{endpoint}/v1/{project_id}/transcodings?task_id=22123973

Example Responses

Status code: 200

Transcoding task queried successfully.

{
  "is_truncated" : 0,
  "total" : 1,
  "task_array" : [ {
    "task_id" : 22123973,
    "status" : "SUCCEEDED",
    "create_time" : 20200310031605,
    "end_time" : 20200310031623,
    "trans_template_id" : [ 4 ],
    "input" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-input.mp4"
    },
    "output" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-output.mp4"
    },
    "output_file_name" : [ "example_480X270.m3u8" ],
    "transcode_detail" : {
      "multitask_info" : [ {
        "template_id" : 4,
        "output_file" : {
          "duration" : 59,
          "duration_ms" : 0,
          "format" : "HLS",
          "size" : 2180,
          "video_info" : {
            "width" : 480,
            "height" : 270,
            "bitrate" : 231,
            "bitrate_bps" : 0,
            "frame_rate" : 25000,
            "codec" : "H264"
          },
          "audio_info" : [ {
            "codec" : "HEAAC",
            "sample" : 44100,
            "channels" : 2,
            "bitrate" : 64,
            "bitrate_bps" : 0
          } ]
        }
      } ],
      "input_file" : {
        "duration" : 59,
        "duration_ms" : 0,
        "format" : "MOV",
        "size" : 2494653,
        "video_info" : {
          "width" : 480,
          "height" : 270,
          "bitrate" : 199,
          "bitrate_bps" : 0,
          "frame_rate" : 25000,
          "codec" : "HEVC"
        },
        "audio_info" : [ {
          "codec" : "AAC",
          "sample" : 48000,
          "channels" : 2,
          "bitrate" : 128,
          "bitrate_bps" : 0
        } ]
      }
    }
  } ]
}

Status code: 400

Failed to query the transcoding task.

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter"
}

Status Codes

Status Code	Description
200	Transcoding task queried successfully.
400	Failed to query the transcoding task.

Error Codes

See Error Codes.

Parent Topic: Transcoding APIs

Previous topic: Canceling a Transcoding Task

Next topic: Deletes Transcoding Task Records

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot