Help Center/ Video On Demand/ API Reference/ Transcoding template management/ Customizes a transcoding template

Updated on 2025-03-25 GMT+08:00

Online Debugging

CLI Examples

View PDF

Customizes a transcoding template

Function

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 H.264 encoding: The value can be 0 or an integer multiple of 2 between 32 and 4,096. H.265 encoding: The value can be 0 or an integer multiple of 2 between 160 and 4,096.
height	No	Integer	Video height H.264 encoding: The value can be 0 or an integer multiple of 2 between 32 and 2,880. H.265 encoding: The value can be 0 or an integer multiple of 2 between 160 and 2,880.
bitrate	Yes	Integer	Average bitrate, in kbit/s. The value can be 0 or an integer between 40 and 30,000.
frame_rate	Yes	Integer	Frame rate, in frames per second (FPS). The value is an integer between 0 and 75. If the value is lower than 5 or higher than 60, the frame rate is 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. Options: AUDIO_CHANNELS_1: mono AUDIO_CHANNELS_2: stereo (default) AUDIO_CHANNELS_5_1: 5.1 audio channel

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

Parent topic: Transcoding template management

Previous topic: Transcoding template management

Next topic: Queries transcoding templates

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot