Updated on 2024-03-14 GMT+08:00

Modifying a Transcoding Template

Function

This API is used to modify a custom transcoding template.

Calling Method

For details, see Calling APIs.

URI

PUT /v1/{project_id}/template/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 .

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

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.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

template_id

Yes

Long

ID of a transcoding template

template_name

Yes

String

Name of the transcoding template.

video

No

Video object

Video information

audio

No

Audio object

Audio information

common

Yes

Common object

Common information

Table 4 Video

Parameter

Mandatory

Type

Description

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: H.264

  • 2: H.265

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. The recommended value is 3.

The default value is 0, indicating that the average output bitrate is adaptive to codec.

  • When codec is set to 1, profile is set to 3.

  • When codec is set to 2, profile is set to 4.

The options are as follows:

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

Its value is 0 or an integer ranging 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

The options are as follows:

  • H.264: The value is 0 or a multiple of 2 from 32 to 4,096.

  • H.265: The value is 0 or a multiple of 2 from 320 to 4,096.

Unit: pixel

Note: If this parameter is set to 0, the video width is an adaptive value.

height

No

Integer

Video height

  • H.264: The value is 0 or a multiple of 2 from 32 to 2,880.

  • H.265: The value is 0 or a multiple of 2 from 96 to 2,880.

Unit: pixel

Note: If this parameter is set to 0, the video height is an adaptive value.

black_cut

No

Integer

Whether to enable black bar removal.

Possible values:

  • 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

Table 5 Audio

Parameter

Mandatory

Type

Description

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.

Table 6 Common

Parameter

Mandatory

Type

Description

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.

Response Parameters

Status code: 403

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

Updates a transcoding template.

PUT https://{endpoint}/v1/{project_id}/template/transcodings/

{
  "template_id" : 1001,
  "template_name" : "MP4_H.264_1920x1080_6000_HEAAC_PVC",
  "video" : {
    "codec" : 1,
    "bitrate" : 6000,
    "profile" : 3,
    "level" : 15,
    "preset" : 3,
    "max_iframes_interval" : 5,
    "black_cut" : 0,
    "bframes_count" : 4,
    "frame_rate" : 1,
    "width" : 1920,
    "height" : 1080
  },
  "audio" : {
    "codec" : 1,
    "sample_rate" : 4,
    "bitrate" : 128,
    "channels" : 2
  },
  "common" : {
    "PVC" : false,
    "hls_interval" : 5,
    "dash_interval" : 5,
    "pack_type" : 1
  }
}

Example Responses

Status code: 403

Failed to modify the transcoding template.

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

Status Codes

Status Code

Description

204

Transcoding template modified successfully.

403

Failed to modify the transcoding template.

Error Codes

See Error Codes.