Creating a Transcoding Task

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)

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.

input

No

ObsObjInfo object

Storage location of an input file. This parameter is mandatory in scenarios where audio is not added.

output

Yes

ObsObjInfo object

Storage location of an output file

trans_template_id

No

Array of integers

Transcoding template ID. If the av_parameter parameter is not contained, this parameter must be carried and its value is an array. Each transcoding output corresponds to a transcoding template ID. A maximum of nine template IDs are supported.

Only the following parameters in transcoding templates can be changed:

Video bitrate, height, and width

trans_template_list

No

Array of TransIdTemplate objects

Transcoding template array

av_parameters

No

Array of AvParameters objects

Transcoding parameter

If both trans_template_id and this parameter are specified, this parameter is preferentially used for transcoding. If trans_template_id is not specified, this parameter is mandatory.

additional_manifests

No

Array of AdditionalManifests objects

Customized parameter for the primary index.

output_filenames

No

Array of strings

Name of an output file. Each transcoded file has a name that corresponds to the sequence of the transcoding template ID array.

• 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 allocated by MPC.

user_data

No

String

Custom user data. You can call a query API or send a notification to transfer this field to users.

watermarks

No

Array of WatermarkRequest objects

Array of image watermarks. Up to 10 watermarks are supported.

thumbnail

No

Thumbnail object

Snapshot information

NOTE:

Snapshots are generated only when the transcoding template specified by trans_template_id or the output resolution specified by av_parameters is 1920 x 1080, 1280 x 720, 854 x 480, or 480 x 270.

thumbnails

No

Array of Thumbnail objects

Multiple screenshot task, array, supports up to 20 members.

priority

No

Integer

Task priority. Possible values:

• 9: high

• 6: medium (default)

subtitle

No

Subtitle object

Subtitle parameters

encryption

No

Encryption object

Encryption parameters

crop

No

Crop object

Number of seconds cropped from a video for which transcoding is performed on.

audio_track

No

AudioTrack object

Audio track parameters

multi_audio

No

MultiAudio object

Multi-language and multi-channel audio parameters

video_process

No

VideoProcess object

Video processing parameters

audio_process

No

AudioProcess object

Audio processing parameters

template_id

Yes

Integer

Output video template ID

output

No

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

No

String

Output file name

video

No

VideoParameters object

Video parameters

audio

No

Audio object

Audio parameters

common

Yes

Common object

Common parameters

output

No

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

No

String

Output file name

output_policy

No

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

No

Integer

Video codec.

Possible values:

• 1: VIDEO_CODEC_H264

• 2: VIDEO_CODEC_H265

crf

No

Object

Factor for controlling the constant video bitrate.

The value range is [0, 51].

max_bitrate

No

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

No

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

No

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

No

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

No

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

No

Integer

Maximum I-frame interval.

The value ranges from 2 to 10.

Default value: 5

Unit: second

bframes_count

No

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

No

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

No

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

No

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

No

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

No

String

Stream name

output_policy

No

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

No

Integer

Audio codec

Possible options are:

• 1: AAC

• 2: HEAAC1

• 3: HEAAC2

• 4: MP3

sample_rate

No

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

No

Integer

Audio bitrate.

The value is 0 or ranges from 8 to 1,000.

Unit: kbit/s

channels

Yes

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

No

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

No

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

No

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

Yes

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.

manifest_name_modifier

No

String

Customized index file name extension

selected_outputs

No

Array of strings

Name of the selected stream

input

No

ObsObjInfo object

Storage location of an input file. This parameter is mandatory if an image watermark is used.

template_id

No

String

ID of a watermark template. You can call an API to create a watermark template.

text_context

No

String

Base64-coded text watermark. This parameter must be configured when type is set to Text.

For example, if the text watermark to be added is "Test Text Watermark", the value of content is 5rWL6K+V5paH5a2X5rC05Y2w.

image_watermark

No

ImageWatermark object

Watermark parameters used for overwriting the parameters with the same names in the watermark template

text_watermark

No

TextWatermark object

Text watermark configurations. If text_context is set, this field cannot be left blank.

dx

No

String

Horizontal offset between the start point of the watermark and the vertex of the output video

Possible options are:

• Integer: horizontal offset between the watermark start point and the video vertex, in pixels. Value range: [0, 4096]

• Decimal: horizontal offset ratio of the watermark start point to the video width. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

For example, if the output video width is 1920 pixels, dx is set to 0.1, and referpos is set to TopRight, the horizontal offset between the upper right corner of the watermark and the right vertex of the video is 192.

dy

No

String

Vertical offset between the start point of the watermark and the vertex of the output video

• Possible options are: Integer: vertical offset between the watermark start point and the video vertex, in pixels. The value range is [0, 4096].

• Decimal: vertical offset ratio of the watermark start point to the video height. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

For example, if the output video height is 1080 pixels, dy is set to 0.1, and referpos is set to TopRight, the vertical offset between the upper right corner of the watermark and the right vertex of the video is 108.

referpos

No

String

Watermark position.

Possible values:

• TopRight: upper right corner

• TopLeft: upper left corner

• BottomRight: lower right corner

• BottomLeft: lower left corner

timeline_start

No

String

Watermark start time, which is used together with timeline_duration.

Its value is a digit.

Unit: second

timeline_duration

No

String

Watermark duration, which is used together with timeline_start.

The value ranges from number to ToEND. ToEND indicates that the watermark lasts until the end of the video.

Default value: ToEND

random_time_min

No

Float

Minimum rotation interval, unit: second

random_time_max

No

Float

Maximum rotation interval time, unit: second

image_process

No

String

Image watermarking method. This parameter is valid only when type is set to Image.

Options:

• Original: Only simple scaling is performed.

• Grayed: Image graying is performed.

• Transparent: The transparency of the source image is retained. If the source image contains transparent areas, these areas remain transparent after transcoding, allowing the underlying background or image to be displayed. This enables seamless fusion between the image and the background.

width

No

String

Watermark image width. The options are as follows:

• Integer: width of a watermark image, in pixels. The value ranges from 8 to 4,096.

• Decimal: ratio of the width to the width of the output video. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

height

No

String

Watermark image height. The options are as follows:

• Integer: height of a watermark image, in pixels. The value ranges from 8 to 4,096.

• Decimal: ratio of the height to the height of the output video. The value is greater than 0 and less than 1, and can contain up to four decimal places, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

base

No

String

Video on which a watermark is overlaid

Options:

• input: A watermark is overlaid on the input file. The size of the watermark in the transcoded file is scaled based on the aspect ratio of the video.

• output: A watermark is overlaid on the transcoded file. The size of the watermark in the transcoded file is not scaled based on the aspect ratio of the video.

dx

No

String

Horizontal offset between the start point of the watermark and the vertex of the output video

Possible options are:

• Integer: horizontal offset between the watermark start point and the video vertex, in pixels. Value range: [0, 4096]

• Decimal: horizontal offset ratio of the watermark start point to the video width. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

For example, if the output video width is 1920 pixels, dx is set to 0.1, and referpos is set to TopRight, the horizontal offset between the upper right corner of the watermark and the right vertex of the video is 192.

dy

No

String

Vertical offset between the start point of the watermark and the vertex of the output video

• Possible options are: Integer: vertical offset between the watermark start point and the video vertex, in pixels. The value range is [0, 4096].

• Decimal: vertical offset ratio of the watermark start point to the video height. The value range is (0, 1). Up to four decimal places are displayed, for example, 0.9999. If the value contains more than four decimal places, the part behind the fourth decimal place is automatically truncated.

For example, if the output video height is 1080 pixels, dy is set to 0.1, and referpos is set to TopRight, the vertical offset between the upper right corner of the watermark and the right vertex of the video is 108.

referpos

No

String

Watermark position.

Possible values:

• TopRight: upper right corner

• TopLeft: upper left corner

• BottomRight: lower right corner

• BottomLeft: lower left corner

timeline_start

No

String

Watermark start time, which is used together with timeline_duration.

Its value is a digit.

Unit: second

timeline_duration

No

String

Watermark duration, which is used together with timeline_start.

The value ranges from number to ToEND. ToEND indicates that the watermark lasts until the end of the video.

Default value: ToEND

random_time_min

No

Float

Minimum rotation interval, unit: second

random_time_max

No

Float

Maximum rotation interval time, unit: second

font_name

No

String

Font. Only fzyouh is supported.

font_size

No

Integer

Font size

The value ranges from 4 to 120.

font_color

No

String

Font color. The options are as follows: black, blue, white, green, red, yellow, brown, gold, pink, orange, and purple

base

No

String

Video on which the watermark is overlaid.

Possible values:

• input: The watermark is overlaid on the input file. After transcoding, the size of the output file is scaled based on the aspect ratio of images.

• output: The watermark is overlaid on the output file.

Default value: input

tar

No

Integer

Whether to compress captured snapshots to a TAR package.

Possible values:

• 0: Captured snapshots are compressed to a TAR package.

• 1: Captured snapshots are not compressed to a TAR package.

out

No

ObsObjInfo object

Storage location of snapshots. If this parameter is not set, snapshots are stored in the same location as the output file.

params

Yes

ThumbnailPara object

Snapshot parameters

type

No

String

Sampling type

Possible options are:

• TIME: Snapshots are captured at certain intervals.

• DOTS: Snapshots are captured at specific time points. Select this type for single snapshot capture.

Default value: TIME

amount

No

Integer

If the proportion of black pixels is greater than or equal to this value, the frame is considered black.

threshold

No

Integer

Pixels with values less than this value are considered black spots.

time

No

Integer

Interval for capturing snapshots.

Default value: 12

Unit: second

start_time

No

Integer

Start time for the sampling type set to TIME. This parameter is used together with time.

Default value: 0

Unit: second

NOTE:

If the value of start_time exceeds the media file duration, frames are not extracted.

duration

No

Integer

Capture duration when the sampling type is set to TIME. This parameter is used together with time and start_time, indicating that the first snapshot is captured at the time specified by start_time and snapshots are captured at the interval specified by time until the duration specified by this parameter elapses.

Value range: [Number, ToEND]. ToEND indicates that snapshot capturing lasts till the end of the video.

Default value: ToEND

Unit: second

NOTE:

0 indicates that snapshot capturing lasts from start_time to the end of the video.

dots

No

Array of integers

Array of time points when a snapshot is captured

For example, if you enter [1,3,5], the image frames at the first, third, and fifth seconds of the video are captured.

• Asynchronous snapshot capturing: A maximum of 10 time points are supported.

• Synchronous snapshot capturing: Only one time point is supported.

dots_ms

No

Array of integers

Time point array of snapshot at a specified time in synchronous snapshot mode, in milliseconds.

For example, enter [1000] to capture the image frame at the 1000th ms position of the video. Only one time point is allowed.

output_filename

No

String

Snapshot file name.

• If only one snapshot is captured (the sampling type is DOTS and only one time point is specified), the output file name is the specified snapshot file name.

• If multiple snapshots are captured (the sampling type is DOTS and multiple time points are specified or the sampling type is TIME), an output file name contains the specified snapshot file name followed by the time point, for example, output_filename_10.jpg.

• If you specify the snapshot to be compressed into a TAR package, the output file name is the TAR package name.

format

No

Integer

Snapshot file format.

The value is:

1: JPG

width

No

Integer

Image width

The options are as follows:

• [96,3840]

• 0: adaptive (the original aspect ratio is retained)

Unit: pixel

height

No

Integer

Image height

The options are as follows:

• [96,2160]

• 0: adaptive (the original aspect ratio is retained)

Unit: pixel

max_length

No

Integer

The longest side of a snapshot. The width of the snapshot is scaled proportionally with the longest side and input video pixel.

The value ranges from 240 to 3,840.

Unit: pixel

NOTE:

This parameter is used together with width/height. If neither width nor height is 0, the image size is calculated based on width/height. Otherwise, the image size is calculated based on max_length. If this parameter and width/height are not selected, snapshots are output based on the aspect ratio of the source media file.

input

No

ObsObjInfo object

Storage location of an SRT file

inputs

No

Array of MulInputFileInfo objects

Storage location of SRT files

subtitle_type

No

Integer

Subtitle file type. Possible values:

• 0: No subtitle file is generated.

• 1: An external subtitle file is inserted into the video stream.

• 2: A WebVTT subtitle file is generated.

language

No

String

Subtitle language tag. The ISO 639-2 encoding format (https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) is recommended.

input

No

ObsObjInfo object

Storage location of a subtitle file

hls_encrypt

No

HlsEncrypt object

Encryption parameters for HLS videos

key

Yes

String

Base64-encoded content encryption key

url

Yes

String

The key carries the service address, and can be decrypted to play HLS segments.

iv

No

String

Initial vector, which is a random number in base64Binary format

algorithm

No

String

Encryption algorithm.

Possible values:

• AES-128-CTR

• AES-128-CBC

Default value: AES-128-CTR

duration

No

Integer

Duration of a captured video, starting from 0 seconds.

Unit: second

type

No

Integer

Audio track selection method.

Possible values:

• 0: selected by default

• 1: selected manually

left

No

Integer

ID of the audio track where the left audio channel is

right

No

Integer

ID of the audio track where the right audio channel is

tracks_info

No

Array of TracksInfo objects

Audio track information

audio_files

No

Array of AudioFile objects

Parameters about a single audio file

default_language

No

String

Default language tag. The ISO 639-2 encoding format (https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) is recommended.

tracks_info

No

Array of TracksInfo objects

Audio track information

input

No

ObsObjInfo object

Storage location of an input file

channel_layout

No

String

Audio channel layout of the audio track

language

No

String

Audio language tag. The ISO 639-2 encoding format (https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) is recommended.

bucket

Yes

String

OBS bucket name

location

Yes

String

Region where an OBS bucket is located. It must be the same as the region where MPC is deployed.

object

Yes

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

No

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.

hls_init_count

No

Integer

Number of HLS start segments

The value ranges from 0 to 10 and defaults to 0.

NOTE:

This parameter is used together with hls_init_interval to specify the duration of the first hls_init_count HLS segments. The value 0 indicates that there are no HLS start segments.

hls_init_interval

No

Integer

Duration of the first hls_init_count HLS segments

The value ranges from 2 to 10 and defaults to 5.

NOTE:

This parameter is valid only when the value of hls_init_count is not 0.

hls_storage_type

No

String

HLS media streams storage

• composite: stored in the same file

• separate: stored in different files

rotate

No

Integer

Clockwise rotation angle of a video.

Possible values:

• 0: Do not rotate.

• 1: Rotate a video by 90 degrees clockwise.

• 2: Rotate a video by 180 degrees clockwise.

• 3: Rotate a video by 270 degrees clockwise.

adaptation

No

String

Adaptive resolution.

Possible values:

• SHORT: adaptive width

• LONG: adaptive height

• NONE: non-adaptive

fill_type

No

String

When adaptation is set to NONE:

• stretch: Stretch, stretch each frame to fill the entire screen.
• black: Keep black, maintain the video's aspect ratio, and fill the remaining edges with black.
• white: Keep white, maintain the video's aspect ratio, and fill the remaining edges with white.

upsample

No

Integer

Whether to enable upsampling, for example, converting a 480p video to a 720p one. Possible values:

• 0: disabled

• 1: enabled

hls_segment_type

No

String

HLS segment type.

Options:

• mpegts: TS

• fmp4: fMP4

If this parameter is not specified, TS segments are used by default.

volume

No

String

Adjusts volume. The options are as follows:

• auto: The volume is automatically adjusted.

• dynamic: The volume is manually adjusted. You need to set the allowed adjustment range.

• original: The volume is not adjusted.

volume_expr

No

Integer

Volume adjustment amplitude. This parameter is used only when volume is set to dynamic.

The value ranges from –15 to 15.

Unit: dB

task_id

Integer

Task ID generated after the task is accepted.

error_code

String

Error code

error_msg

String

Error description

202

Transcoding task created successfully.

403

Failed to create a transcoding task.