Querying Transcoding Tasks

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID. (tag:hc,hk)

Project ID. For details about how to obtain the project ID, see [Obtaining a Project ID]. (tag:hcso,g42,cmcc)

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

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.

task_array

Array of QueryTranscodingsTaskResponse objects

List of transcoding tasks

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

task_id

String

Task ID

status

String

Task status

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

Screenshot file information.

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.

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

template_id

Integer

Template ID

error

ErrorResponse object

Error message about failed transcoding

output_file

SourceInfo object

Information about a single output

error_code

String

Error code

error_msg

String

Error 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

The MD5 value of the video.

video_info

VideoInfo object

Video information

audio_info

Array of AudioInfo objects

Audio information

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

duration

String

Video stream duration, unit: seconds

duration_ms

String

Video stream duration, unit: milliseconds

rotate

Float

The angle of the video shot, in degrees.

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, unit: seconds

duration_ms

String

Audio stream duration, unit: milliseconds

pic_info

Array of PicInfo objects

Screenshot file information.

output

ObsObjInfo object

Output file information.

output_name

String

The name of the screenshot compression package.

pic_name

String

Snapshot file name

video

VideoParameters object

Video parameters

audio

Audio object

Audio parameters

common

Common object

Common parameters

output

ObsObjInfo object

Output path, if not filled, will be combined with the outer layer transcoding output. Explanation: When multiple HLS outputs are used, if the output paths are different, index.m3u8 will not be available, and audio and video separation will not be available.

output_filename

String

Output file name

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

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.

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.

Possible options:

• 1: VIDEO_PRESET_SPEED (fast encoding)

• 2: VIDEO_PRESET_NORMAL (common encoding), which is not recommended

• 3: VIDEO_PRESET_HIGHQUALITY (high-quality encoding)

Default value: 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

The options are as follows:

• H264: The value ranges from 0 to 8 and defaults to 4.

• H.265: The value ranges from 0 to 8 and defaults to 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

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.

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.

The value ranges from 2 to 10.

Unit: second

dash_interval

Integer

DASH segment duration. This parameter is used only when pack_type is set to 2 or 3.

The value ranges from 2 to 10.

Unit: second

pack_type

Integer

Packaging type

Possible options are:

• 1: HLS

• 2: DASH

• 3: HLS+DASH

• 4: MP4

• 5: MP3

• 6: ADTS

NOTE:

If pack_type is set to 5 or 6, do not configure video parameters.

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.

manifest_name_modifier

String

Customized index file name extension

selected_outputs

Array of strings

Name of the selected stream

error_code

String

Error code

error_msg

String

Error description

200

Transcoding task queried successfully.

400

Failed to query the transcoding task.