Updated on 2023-12-25 GMT+08:00

Querying Transcoding Templates

Function

Queries one or more custom transcoding templates. You can query up to 10 templates by ID or page number.

Calling Method

For details, see Calling APIs.

URI

GET /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 .

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

template_id

No

Array

ID of a transcoding template. A maximum of 10 transcoding template IDs can be queried at a time.

page

No

Integer

Page number. This parameter is invalid when task_id is specified.

Default value: 0

size

No

Integer

Number of records on each page. If template_id is specified, this parameter is invalid. The value ranges from 1 to 100.

Request Parameters

Table 3 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.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

template_array

Array of TemplateInfo objects

Details about the transcoding templates

total

Integer

Total number of transcoding templates

Table 5 TemplateInfo

Parameter

Type

Description

template_id

Integer

ID of each queried transcoding template

template

QueryTransTemplate object

Configurations built in the transcoding templates

Table 6 QueryTransTemplate

Parameter

Type

Description

template_name

String

Name of a transcoding template

video

Video object

Video information

audio

Audio object

Audio information

common

Common object

Common information

Table 7 Video

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

  • 2: H.265

bitrate

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

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

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.

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

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

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

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 8 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 9 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.

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.

Status code: 403

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

GET https://{endpoint}/v1/{project_id}/templates/transcoding?template_id=80985

Example Responses

Status code: 200

Transcoding template queried successfully.

{
  "template_array" : [ {
    "template_id" : 80985,
    "template" : {
      "template_name" : "test_template",
      "video" : {
        "output_policy" : "transcode",
        "codec" : 1,
        "bitrate" : 0,
        "profile" : 3,
        "level" : 15,
        "preset" : 3,
        "max_iframes_interval" : 5,
        "bframes_count" : 4,
        "frame_rate" : 0,
        "width" : 0,
        "height" : 0,
        "black_cut" : 0
      },
      "audio" : {
        "output_policy" : "transcode",
        "codec" : 1,
        "bitrate" : 0,
        "sample_rate" : 1,
        "channels" : 2
      },
      "common" : {
        "PVC" : false,
        "hls_interval" : 5,
        "dash_interval" : 5,
        "pack_type" : 1
      }
    }
  } ],
  "total" : 1
}

Status code: 403

Failed to query the transcoding template.

{
  "error_code" : "MPC.10212",
  "error_msg" : "Operation failed."
}

Status Codes

Status Code

Description

200

Transcoding template queried successfully.

403

Failed to query the transcoding template.

Error Codes

See Error Codes.