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

Creating a Transcoding Template Group

Function

This API is used to create a transcoding template group. In a custom transcoding template group, a maximum of six output configurations can be defined.

URI

POST /v1/{project_id}/template_group/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

name

No

String

Name of each queried template group

videos

No

Array of VideoObj objects

List of output video configurations

audio

No

Audio object

Audio parameters

video_common

No

VideoCommon object

Common video parameters

common

No

Common object

Common parameters
Table 4 VideoObj

Parameter

Mandatory

Type

Description

width

Yes

Integer

Video width (unit: px). The value can be:

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

  • A multiple of 4 from 240 to 2880 for H.265.

height

Yes

Integer

Video height (unit: px). The value can be:

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

  • A multiple of 4 from 240 to 2880 for H.265.

bitrate

Yes

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.
Table 5 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 6 VideoCommon

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

profile

No

Integer

Encoding profile. The recommended value is 3.

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

preset

No

Integer

Encoding quality.

Possible values are:

  • 1: VIDEO_PRESET_HSPEED2

  • 2: VIDEO_PRESET_HSPEED

  • 3: VIDEO_PRESET_NORMAL

NOTE:

A larger value indicates higher encoding quality and longer transcoding time.

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.

Its value is 0 or an integer ranging from 5 to 30.

aspect_ratio

No

Integer

Aspect ratio.

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

Response Parameters

Status code: 201

Table 8 Response body parameters

Parameter

Type

Description

template_group

TemplateGroup object

Details about the custom template group
Table 9 TemplateGroup

Parameter

Type

Description

group_id

String

ID of each queried template group

name

String

Name of each queried template group

template_ids

Array of integers

IDs of templates in each queried template group

videos

Array of VideoAndTemplate objects

List of output video configurations

audio

Audio object

Audio information

video_common

VideoCommon object

Common video information

common

Common object

Common information
Table 10 VideoAndTemplate

Parameter

Type

Description

template_id

Integer

Template ID

width

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

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.

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.
Table 11 Audio

Parameter

Type

Description

output_policy

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

Integer

Audio codec.

Possible values are:

  • 1: AAC

  • 2: HEAAC1

  • 3: HEAAC2

  • 4: MP3

sample_rate

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

Integer

Audio bitrate.

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

Unit: kbit/s

channels

Integer

Number of audio channels.

Possible values are:

  • 1: AUDIO_CHANNELS_1

  • 2: AUDIO_CHANNELS_2

  • 6: AUDIO_CHANNELS_5_1
Table 12 VideoCommon

Parameter

Type

Description

output_policy

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

Integer

Video codec.

Possible values are:

  • 1: VIDEO_CODEC_H264

  • 2: VIDEO_CODEC_H265

profile

Integer

Encoding profile. The recommended value is 3.

Possible values are:

  • 1: VIDEO_PROFILE_H264_BASE

  • 2: VIDEO_PROFILE_H264_MAIN

  • 3: VIDEO_PROFILE_H264_HIGH

  • 4: VIDEO_PROFILE_H265_MAIN

level

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

preset

Integer

Encoding quality.

Possible values are:

  • 1: VIDEO_PRESET_HSPEED2

  • 2: VIDEO_PRESET_HSPEED

  • 3: VIDEO_PRESET_NORMAL

NOTE:

A larger value indicates higher encoding quality and longer transcoding time.

ref_frames_count

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

Integer

Maximum I-frame interval.

The value ranges from 2 to 10.

Default value: 5

Unit: second

bframes_count

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

Integer

Frame rate.

Its value is 0 or an integer ranging from 5 to 30.

aspect_ratio

Integer

Aspect ratio.

black_cut

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 13 Common

Parameter

Type

Description

PVC

Boolean

Whether to enable low bitrate HD. Possible values are:

  • false: disabled.

  • true: enabled.

Default value: false

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.

Default value: 5

Unit: s

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.

Default value: 5

Unit: s

pack_type

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.

Status code: 400

Table 14 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

```
POST https://{endpoint}/v1/{project_id}/template_group/transcodings
{
  "name" : "my_templateGroup",
  "videos" : [{
          "width" : "480",
          "height" : "270",
          "bitrate" : "200"
      }
  ],
  "audio" : {
      "codec" : 1,
      "sample_rate" : 1,
      "channels" : 2,
      "bitrate" : 0
  },
  "video_common" : {
      "codec" : 1,
      "black_cut" : 0,
      "aspect_ratio" : 0,
      "profile" : 3,
      "level" : 15,
      "preset" : 3,
      "ref_frames_count" : 4,
      "max_iframes_interval" : 5,
      "bframes_count" : 4,
      "frame_rate" : 0
  },
  "common" : {
      "PVC" : 0,
      "pack_type" : 1,
      "hls_interval" : 5,
      "dash_interval" : 5
  }
}
```

Example Responses

Status code: 201

Transcoding template group created successfully.

{
  "template_group" : {
    "group_id" : "f7fc420b17db414fb11652671581bb6d",
    "name" : "my_templateGroup",
    "template_ids" : [ 286548 ],
    "videos" : [ {
      "template_id" : 286548,
      "width" : 480,
      "height" : 270,
      "bitrate" : 200
    } ],
    "audio" : {
      "output_policy" : "transcode",
      "codec" : 1,
      "bitrate" : 0,
      "sample_rate" : 1,
      "channels" : 2
    },
    "video_common" : {
      "output_policy" : "transcode",
      "codec" : 1,
      "profile" : 3,
      "level" : 15,
      "preset" : 1,
      "ref_frames_count" : 4,
      "max_iframes_interval" : 5,
      "bframes_count" : 4,
      "frame_rate" : 0,
      "sync_timestamp" : false,
      "aspect_ratio" : 0,
      "black_cut" : 0,
      "GOP_structure" : false,
      "sr_factor" : null
    },
    "common" : {
      "QDS" : false,
      "PVC" : false,
      "PVC_version" : null,
      "PVC_strength" : 100,
      "hls_interval" : 5,
      "dash_interval" : 5,
      "pack_type" : 1
    }
  }
}

Status code: 400

Failed to create a transcoding template group.

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

Status Codes

Status Code

Description

201

Transcoding template group created successfully.

400

Failed to create a transcoding template group.

Error Codes

See Error Codes.