Help Center/ Video On Demand/ API Reference/ Transcoding template management/ Customizes a transcoding template
Updated on 2024-12-04 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Customizes a transcoding template

Function

Customizes a transcoding template

URI

POST /v2/{project_id}/asset/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. This parameter is mandatory when token authentication is used.

It 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 a token.

Authorization

No

String

Authentication information. This parameter is mandatory for AK/SK authentication.

X-Sdk-Date

No

String

Time when the request is sent. This parameter is mandatory for AK/SK authentication.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Template group name.

is_default

No

Boolean

Indicates whether the template is the default transcoding template. The default value is false. If the value is not specified, the default value is used.

is_auto_encrypt

No

Boolean

Whether to encrypt the output audio/video. The default value is false (not encrypted).

Only HLS audio/video streams can be encrypted before being output. Original audio/video streams are not encrypted. This field is unavailable for non-HLS transcoded audio/video. Before enabling this function, obtain the key URL by referring to section "HLS Encryption Settings" in VOD User Guide.

quality_info_list

Yes

Array of QualityInfoList objects

Image quality configuration list.

common

Yes

CommonInfo object

Low-bitrate HD transcoding switch, encoding format, and multi-stream common parameters.

watermark_template_ids

No

Array of strings

ID array of the bound watermark template group.

description

No

String

Template description.
Table 4 QualityInfoList

Parameter

Mandatory

Type

Description

video

No

VideoInfo object

Video template information. Configure at least one of the video and audio parameters.

audio

No

AudioInfo object

Audio template information
Table 5 VideoInfo

Parameter

Mandatory

Type

Description

quality

Yes

String

Video quality.

  • The default 4K resolution is 3840 x 2160 and the bitrate is 8000 kbit/s.

  • The default 2K resolution is 2560 x 1440 and the bitrate is 7000 kbit/s.

  • The default FULL_HD resolution is 1920 x 1080 and the bitrate is 3000 kbit/s.

  • The default HD resolution is 1280 x 720 and the bitrate is 1000 kbit/s.

  • The default SD resolution is 854 x 480 and the bitrate is 600 kbit/s.

  • The default FLUENT resolution is 480 x 270 and the bitrate is 300 kbit/s.

width

No

Integer

Video width.

height

No

Integer

Video height.

bitrate

Yes

Integer

Bitrate, in kbit/s.

frame_rate

Yes

Integer

Frame rate, expressed in frames per second (FPS).

The value is 0 or an integer ranging from 5 to 60.

The default value is 0 (adaptive).
Table 6 AudioInfo

Parameter

Mandatory

Type

Description

sample_rate

Yes

String

Audio sampling rate. Possible options:

  • AUDIO_SAMPLE_AUTO (default)

  • AUDIO_SAMPLE_22050: 22050 Hz

  • AUDIO_SAMPLE_32000: 32000 Hz

  • AUDIO_SAMPLE_44100: 44100 Hz

  • AUDIO_SAMPLE_48000: 48000 Hz

  • AUDIO_SAMPLE_96000: 96000 Hz

bitrate

No

Integer

Audio bitrate, in kbit/s.

channels

Yes

String

Number of audio channels. Possible options:

  • AUDIO_CHANNELS_1: mono

  • AUDIO_CHANNELS_2: stereo

  • AUDIO_CHANNELS_5_1: 5.1 audio
Table 7 CommonInfo

Parameter

Mandatory

Type

Description

pvc

No

Boolean

Low-bitrate HD transcoding switch.

video_codec

No

String

Video encoding format

  • H264

  • H265

audio_codec

No

String

Audio encoding format.

  • AAC: AAC (default)

  • HEAAC1: HEAAC1

  • HEAAC2: HEAAC2

  • MP3: MP3

is_black_cut

No

Boolean

Black bar cropping type. The default value is false, indicating that black bar cropping is disabled.

format

Yes

String

Transcoded file format

  • MP4

  • HLS

  • DASH

  • DASH_HLS

  • MP3

  • ADTS

  • UNKNOW

hls_interval

No

Integer

Segment file duration. The value ranges from 2 to 10 (in seconds) and defaults to 5.

upsample

No

Boolean

Whether to enable upsampling. After this function is enabled, video resolution can be improved and the number of sampling points can be increased. The default value is false, indicating that upsampling is disabled.

adaptation

No

String

Resolution adaptation mode of the transcoded media file.

Options:

  • SHORT: adaptive short side The width and height of the transcoding template are specified. The long side of the source media file is scaled based on the ratio between the short side of the transcoding template and the short side of the source media file.

  • LONG: adaptive long side The width and height of the transcoding template are specified. The short side of the source media file is scaled based on the ratio between the long side of the transcoding template and the long side of the source media file.

  • NONE (default): adaptive to the specified aspect ratio The output resolution is based on the width and height set in the transcoding template.

NOTE:

  • This parameter cannot be set for the V1 API (discarded). The default value is SHORT. The default value is NONE for the V2 API. The default value of the V1 API is different from that of the V2 API. Pay attention to the value of this parameter when calling the API.

  • The default value of the transcoding template created using the V2 API on the console is SHORT, which is the same as that of the transcoding template created using the V1 API.

preset

No

Integer

Encoding quality level. Options: 0: default mode; 1: transcoding efficiency first; 2: transcoding quality first.

max_iframes_interval

No

Integer

Maximum I-frame interval. Value range: [2, 10]. The default value is 5, in second.

hls_audio_separate

No

Boolean

Whether to store the transcoded audio separately.

hls_segment_type

No

String

Packaging format of HLS segments. Currently, TS (default) and fMP4 are supported.

Response Parameters

Status code: 201

Table 8 Response body parameters

Parameter

Type

Description

group_id

String

Template group ID.

Status code: 400

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

Creates a transcoding template.

POST https://{endpoint}/v2/{project_id}/asset/template/transcodings

Content-Type: application/json
{
  "name": "trans_template_test",
  "is_default": true,
  "is_auto_encrypt": false,
  "quality_info_list": [
    {
      "video": {
        "width": 1280,
        "height": 720,
        "bitrate": 1000,
        "quality": "HD",
        "frame_rate": 0
      },
      "audio": {
        "sample_rate": "AUDIO_SAMPLE_AUTO",
        "channels": "AUDIO_CHANNELS_1",
        "bitrate": 0
      }
    }
  ],
  "watermark_template_ids": [],
  "common": {
    "pvc": false,
    "video_codec": "H264",
    "audio_codec": "AAC",
    "format": "HLS",
    "hls_interval": 5
  }
}

Example Responses

Status code: 201

The information is returned when the request succeeded.

{
  "group_id" : "f9b045e0811c482f9de0d436a5927bb6"
}

Status code: 400

The information is returned when the request failed.

{
  "error_code" : "VOD.10053",
  "error_msg" : "The request parameter is illegal, illegal field: {xx}."
}

Status Codes

Status Code

Description

201

The information is returned when the request succeeded.

400

The information is returned when the request failed.

Error Codes

See Error Codes.