Help Center> Media Processing Center> API Reference> Transcoding APIs> Creating a Transcoding Task
View PDF

Creating a Transcoding Task

Function

This API is used to create a transcoding task to transcode media files, and add watermarks and capture snapshots during transcoding. A transcoding template must be configured before video transcoding. Ensure that an input media file is stored in an OBS bucket in the same region as MPC and the permission for accessing the OBS bucket has been granted to MPC.

URI

POST /v1/{project_id}/transcodings

Table 1 Path parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see Obtaining a Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token.

The token is obtained by calling the IAM API used to obtain a user token. The token is the value of X-Subject-Token in the response header.

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.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

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 av_parameter is not specified, this parameter is mandatory. 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.

av_parameters

No

Array of AvParameters objects

Transcoding parameters.

If trans_template_id and this parameter are both set, transcode audio or video based on the settings defined in this parameter. If trans_template_id is not set, this parameter is mandatory.

output_filenames

No

Array of strings

Name of an output file.

  • 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

A maximum of 20 image watermarks and text watermarks are supported.

thumbnail

No

Thumbnail object

Snapshot information. Snapshot files are generated only when the output resolution set in the transcoding template or av_parameters is 1920x1080, 1280x720, 854x480, or 480x270. Otherwise, no snapshot files are generated.

priority

No

Integer

Task priority.

Possible values are:

  • 9: high

  • 6: medium

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
Table 4 AvParameters

Parameter

Mandatory

Type

Description

video

No

VideoParameters object

Video parameters

audio

No

Audio object

Audio parameters

common

Yes

Common object

Common parameters
Table 5 VideoParameters

Parameter

Mandatory

Type

Description

output_policy

No

String

Output policy.

Possible values are:

  • discard

  • transcode

NOTE:

  • If output_policy in the video parameters is discard and output_policy in the audio parameters is transcode, only audio is transcoded.

  • If output_policy in the video parameters is transcode and output_policy in the audio parameters is discard, only video is transcoded.

  • If both are discard, the settings are invalid.

  • If both are transcode, audio and video are transcoded.

codec

No

Integer

Video codec.

Possible values are:

  • 1: VIDEO_CODEC_H264

  • 2: VIDEO_CODEC_H265

bitrate

No

Integer

Average output bitrate.

Its value is 0 or an integer ranging from 40 to 30,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 are:

  • 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.

Possible values are:

  • 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

  • 16: VIDEO_LEVEL_x_x

preset

No

Integer

Encoding quality.

Possible values are:

  • 1: VIDEO_PRESET_HSPEED2 (only used for H.265)

  • 2: VIDEO_PRESET_HSPEED (only used for H.265)

  • 3: VIDEO_PRESET_NORMAL (available for H.264 and H.265, default option for H.265)

ref_frames_count

No

Integer

Maximum reference frames.

Value range:

  • H.264: 1 to 8. The default value is 4.

  • H.265: The value is fixed at 4.

Unit: frame

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 number of B-frames.

Value range:

  • H.264: 0 to 7. The default value is 4.

  • H.265: 0 to 7. The default value is 7.

Unit: frame

frame_rate

No

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.

width

No

Integer

Video width (unit: px).

The value can be:

  • A multiple of 2 from 32 to 4,096 for H.264.

  • A multiple of 4 from 320 to 4,096 for H.265.

height

No

Integer

Video height (unit: px).

The value can be:

  • A multiple of 2 from 32 to 2,880 for H.264.

  • A multiple of 4 from 240 to 2,880 for H.265.

black_cut

No

Integer

Whether to enable black bar removal.

Possible values are:

  • 0: Disable black bar removal.

  • 1: Enable black bar removal and low-complexity algorithms for long videos (>5 minutes).

  • 2: Enable black bar removal and high-complexity algorithms for short videos (≤5 minutes).
Table 6 Audio

Parameter

Mandatory

Type

Description

output_policy

No

String

Output policy.

Possible values are:

  • discard

  • transcode

NOTE:

  • If output_policy in the video parameters is discard and output_policy in the audio parameters is transcode, only audio is transcoded.

  • If output_policy in the video parameters is transcode and output_policy in the audio parameters is discard, only video is transcoded.

  • If both are discard, the settings are invalid.

  • If both are transcode, audio and video are transcoded.

codec

Yes

Integer

Audio codec.

Possible values are:

  • 1: AAC

  • 2: HEAAC1

  • 3: HEAAC2

  • 4: MP3

sample_rate

Yes

Integer

Audio sampling rate.

Possible values are:

  • 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)

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.

Possible values are:

  • 1: AUDIO_CHANNELS_1

  • 2: AUDIO_CHANNELS_2

  • 6: AUDIO_CHANNELS_5_1
Table 7 Common

Parameter

Mandatory

Type

Description

PVC

Yes

Boolean

Whether to enable low bitrate HD. Possible values are:

  • false: disabled.

  • true: enabled.

Default value: false

hls_interval

Yes

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.

Default value: 5

Unit: s

dash_interval

Yes

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.

Default value: 5

Unit: s

pack_type

Yes

Integer

Packaging type.

Possible values 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 set video parameters.
Table 8 WatermarkRequest

Parameter

Mandatory

Type

Description

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.

For example, if the text watermark to be added is "Test Text Watermark", the value 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.
Table 9 ImageWatermark

Parameter

Mandatory

Type

Description

dx

No

String

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

  • Integer: horizontal offset between the image start point and the video vertex, in pixelsThe value ranges from 0 to 4,096.

  • Decimal: horizontal offset ratio of the image start point relative to the video widthA maximum of four decimal places are supported, for example, 0.9999.

For example, if the output video width is 1,920 pixels, dx is 0.1, and referpos is 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.

  • Integer: vertical offset between the image start point and the video vertex, in pixels.The value ranges from 0 to 4,096.

  • Decimal: vertical offset ratio of the image start point relative to the video heightA maximum of four decimal places are supported, for example, 0.9999.

For example, if the output video height is 1,080 pixels, dy is 0.1, and referpos is 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 are:

  • TopRight: upper right corner

  • TopLeft: upper left cornerBottom

  • Right: 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: s

timeline_duration

No

String

How long the watermark lasts, which is used together with timeline_start.

Its value is a digit greater than or equal to 0.

Default value: ToEND

ToEND indicates that the watermark lasts until the end of the video.

image_process

No

String

How the image watermark is processed. This parameter is used only when type is set to Image.

Possible values are:

  • Original: simple scaling

  • Grayed: Turn the color image to gray.

  • Transparent: transparent

width

No

String

Watermark width.

The value can either be a positive integer or a decimal between 0.0 and 1.0.

  • Integer: pixel value of the watermark width (unit: px)The value ranges from 8 to 4,096.

  • Decimal: ratio between the video width and watermark widthA maximum of four decimal places are supported, for example, 0.9999.

height

No

String

Watermark height.

The value can either be a positive integer or a decimal between 0.0 and 1.0.

  • Integer: pixel value of the watermark height (unit: px)The value ranges from 8 to 4,096.

  • Decimal: ratio between the video height and watermark heightA maximum of four decimal places are supported, for example, 0.9999.

base

No

String

Video which the watermark is overlaid on.

Possible values are:

  • input: The watermark is overlaid on the input video. The actual size of the output video is scaled proportionally based on the watermark size.

  • output: The watermark is overlaid on the output file.
Table 10 TextWatermark

Parameter

Mandatory

Type

Description

dx

No

String

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

  • Integer: horizontal offset between the image start point and the video vertex, in pixelsThe value ranges from 0 to 4,096.

  • Decimal: horizontal offset ratio of the image start point relative to the video widthA maximum of four decimal places are supported, for example, 0.9999.

For example, if the output video width is 1,920 pixels, dx is 0.1, and referpos is 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.

  • Integer: vertical offset between the image start point and the video vertex, in pixels.The value ranges from 0 to 4,096.

  • Decimal: vertical offset ratio of the image start point relative to the video heightA maximum of four decimal places are supported, for example, 0.9999.

For example, if the output video height is 1,080 pixels, dy is 0.1, and referpos is 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 are:

  • TopRight: upper right corner

  • TopLeft: upper left cornerBottom

  • Right: 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: s

timeline_duration

No

String

How long the watermark lasts, which is used together with timeline_start.

Its value is a digit greater than or equal to 0.

Default value: ToEND

ToEND indicates that the watermark lasts until the end of the video.

font_name

No

String

Text watermark font.

Possible values are:

  • fzyouh

  • msyh

font_size

No

Integer

Font size.

Value range: 4 to 120

font_color

No

String

Font color.

Possible values are:

  • black

  • blue

  • white

  • green

  • red

  • yellow

  • brown

  • gold

  • pink

  • orange

  • purple

base

No

String

Video which the watermark is overlaid on. 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.
Table 11 Thumbnail

Parameter

Mandatory

Type

Description

tar

No

Integer

Whether to compress captured snapshots to a TAR package

Possible values are:

  • 0: Yes

  • 1: No

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
Table 12 ThumbnailPara

Parameter

Mandatory

Type

Description

type

No

String

Sampling type.

Possible values are:

  • PERCENT: Snapshots are captured based on the percentage of the video duration.

  • TIME: Snapshots are captured at certain intervals.

  • DOTS: Snapshots are captured a fixed time point.

Default value: TIME

time

No

Integer

Interval for taking snapshots.

Default value: 12

Unit: second

start_time

No

Integer

Start time if the sampling type is TIME. This parameter is used together with time.

Default value: 0

Unit: second

duration

No

Integer

Duration if the sampling type is TIME. This parameter is used together with time and start_time. Snapshots are captured every time.

ToEND indicates that sampling lasts until the end of the video.

Default value: ToEND

Unit: second

It must be greater than or equal to 0. If this is 0, snapshots are captured from start_time to the video end time.

dots

No

Array of integers

Array of time points when a snapshot is taken. A maximum of 10 time points are supported.

output_filename

No

String

Name of a snapshot file.

  • If only one image is extracted (the sampling type is DOTS), the image is output based on the specified file name.

  • If multiple images are extracted (the sampling type is DOTS or TIME), the time point is added to the name of the output image file, for example, output_filename_10.jpg.

  • If extracted images are going to be compressed into a TAR package, the TAR package is generated based on the specified file name.

format

No

Integer

Snapshot file format.

The value is:

1: jpg

aspect_ratio

No

Integer

Aspect ratio.

width

No

Integer

Snapshot width

height

No

Integer

Snapshot height

max_length

No

Integer

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

Value range: 240 to 3,840

Default value: 480

Unit: pixel

NOTE:

If this parameter and width/height are both set, the width/height is used. If both the width and height are not 0, the longest side is the width/height. Otherwise, the longest side is the value of max_length. If this parameter and width/height are not set, max_length is 480 by default.
Table 13 Subtitle

Parameter

Mandatory

Type

Description

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: external subtitle file.

  • 2: WebVTT file.
Table 14 MulInputFileInfo

Parameter

Mandatory

Type

Description

language

No

String

Language label

input

No

ObsObjInfo object

Storage location of a subtitle file
Table 15 Encryption

Parameter

Mandatory

Type

Description

hls_encrypt

No

HlsEncrypt object

Encryption parameters for HLS videos
Table 16 HlsEncrypt

Parameter

Mandatory

Type

Description

key

Yes

String

Content encryption key, which is in base64Binary format

url

Yes

String

Address of Key Management Service (KMS) used by the tenant

iv

No

String

Initial vector, which is a random number in base64Binary format

algorithm

No

String

Encryption algorithm.

Possible values are:

  • AES-128-CTR

  • AES-128-CBC

  • SM4CBC

Default value: AES-128-CTR
Table 17 Crop

Parameter

Mandatory

Type

Description

duration

No

Integer

Duration of a captured video, starting from 0 seconds.

Default value: 10

Unit: s
Table 18 AudioTrack

Parameter

Mandatory

Type

Description

type

No

Integer

Audio track selection method.

Possible values are:

  • 0: default selection

  • 1: manual selection

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
Table 19 MultiAudio

Parameter

Mandatory

Type

Description

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 track language.
Table 20 AudioFile

Parameter

Mandatory

Type

Description

tracks_info

No

Array of TracksInfo objects

Audio track information

input

No

ObsObjInfo object

Storage location of an input file
Table 21 TracksInfo

Parameter

Mandatory

Type

Description

channel_layout

No

String

Audio channel layout of the audio track

language

No

String

Language description of the audio track
Table 22 ObsObjInfo

Parameter

Mandatory

Type

Description

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

File path.

  • If this parameter is used for an input, a specific path must be specified.

  • If this parameter is used for an output, only the directory for storing the outputs needs to be specified.

file_name

No

String

Name of an output file. This parameter is valid only for packaging tasks.

  • 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.
Table 23 VideoProcess

Parameter

Mandatory

Type

Description

rotate

No

Integer

Clockwise rotation angle of a video.

Possible values are:

  • 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 are:

  • SHORT: adaptive width

  • LONG: adaptive height

  • NONE: Do not adapt.

upsample

No

Integer

Whether to enable low resolution-to-high resolution, for example, 480p to 720p. Possible values are:

  • 0: disabled.

  • 1: enabled.
Table 24 AudioProcess

Parameter

Mandatory

Type

Description

volume

No

String

Volume adjustment method. In this case, the volume adjustment amplitude needs to set.

Possible values are:

  • auto: Adjust the volume automatically.

  • dynamic: Adjust the volume manually.

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

Response Parameters

Status code: 202

Table 25 Response body parameters

Parameter

Type

Description

task_id

Integer

Task ID. If the returned status code is 200 OK, the value is the task ID generated after the task is accepted.

Status code: 403

Table 26 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

POST https://{endpoint}/v1/{project_id}/transcodings
{
  "input": {
        "bucket": "example-bucket",
        "location": "region1",
        "object": "/VOD/input/sample.MP4"
        },
  "output": {
        "bucket": "example-bucket",
        "location": "region1",
        "object": "/VOD/output/"
      },
   "trans_template_id": [1002, 1003, 1004, 1005],
   "priority": "9",
   "subtitle": {
        "subtitle_type": 1,
        "input": {
                "bucket": "bucket",
                "location": "region1",
                "object": "subtitle.srt"
          }
       },
    "encryption": {
       "multidrm": {
          "content_id": "123456789",
          "streaming_mode": "HLS ",
          "encrypt_audio": 0,
          "emi": 16420,
          "drm_list": ["PLAYREADY"]
       }
     },
    "thumbnail": {
     "out": {
        "bucket": "example-bucket",
        "location": "region1",
        "object": "/VOD/output/"
      },
    "tar": 1,
     "params": {
        "time": 2,
        "format": 1,
        "aspect_ratio": 1,
        "max_length": 480
    }
    }
}

Example Responses

Status code: 202

Transcoding task created successfully.

{
  "task_id" : 100211
}

Status code: 403

Failed to create a transcoding task.

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

Status Codes

Status Code

Description

202

Transcoding task created successfully.

403

Failed to create a transcoding task.

Error Codes

See Error Codes.

Parent topic: Transcoding APIs