Help Center/ Video On Demand/ API Reference/ Transcoding Template Management/ Creating a Transcoding Template

Updated on 2025-11-26 GMT+08:00

View PDF

Creating a Transcoding Template

Function

This API is used to create a custom transcoding template.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

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 the user token.
Authorization	No	String	Authentication information. This parameter is mandatory for AK/SK authentication.
X-Sdk-Date	No	String	Time when a 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	Whether the template is set as the default transcoding template. The default value is false, which means the template is not set as the default one.
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.
common	Yes	CommonInfo object	Parameters shared by the low-bitrate HD transcoding and multi-channel encoding format.
watermark_template_ids	No	Array of strings	Array of IDs for the associated watermark templates.
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	Image quality. 4K 3840 × 2160, 8,000 kbit/s 2K: 2560 × 1440, 7,000 kbit/s FULL_HD: 1920 × 1080, 3,000 kbit/s HD: 1280 × 720, 1,000 kbit/s SD: 854 × 480, 600 kbit/s FLUENT: 480 × 270, 300 kbit/s
width	No	Integer	Video width. H.264 encoding: The value can be 0 or an integer multiple of 2 from 32 to 4,096. H.265 encoding: The value can be 0 or an integer multiple of 2 from 160 to 4,096.
height	No	Integer	Video height. H.264 encoding: The value can be 0 or an integer multiple of 2 from 32 to 2,880. H.265 encoding: The value can be 0 or an integer multiple of 2 from 160 to 2,880.
bitrate	Yes	Integer	Average bitrate, in kbit/s. The value can be 0 or an integer from 40 to 30,000.
frame_rate	Yes	Integer	Frame rate, in frames per second (FPS). The value is an integer from 0 to 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. The options include: 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 (default) HEAAC1 HEAAC2 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. The options include: 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. Value range: [0,2]. 0: default mode; 1: transcoding efficiency first; 2: transcoding quality first.
max_iframes_interval	No	Integer	Maximum I-frame interval. Value range: [2, 10]. Default value: 5, in seconds
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

This example 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

Returned when the request succeeded.

{
  "group_id" : "f9b045e0811c482f9de0d436a5927bb6"
}

Status code: 400

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	Returned when the request succeeded.
400	Returned when the request failed.

Error Codes

See Error Codes.

Parent topic: Transcoding Template Management

Previous topic: Transcoding Template Management

Next topic: Querying 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