AddTemplate - ApsaraVideo Media Processing - Alibaba Cloud Documentation Center

Creates a custom transcoding template. You need to configure the information such as the container format, video stream settings, and audio stream settings.

Operation description

When you call this operation, you need to set transcoding parameters such as those related to the container format, video stream, and audio stream. If you do not specify some parameters, streams that are generated by using the template do not contain the information specified by those parameters.

QPS limit

You can call this operation up to 100 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limit.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
mts:AddTemplate	create	All Resources ``	none	none

Request parameters

Parameter	Type	Required	Description	Example
Name	string	Yes	The name of the transcoding template. The name can be up to 128 bytes in length.	mps-example
Container	string	No	The container format. The value must be a JSON object that contains the Format parameter. If you do not specify this parameter, the transcoded media file is in MP4 format by default. This parameter is required if you want to use the transcoding template to generate media files in other formats. For more information, see Container . Default value: MP4. Video transcoding supports the following formats: FLV, MP4, HLS (M3U8 + TS), and MPEG-DASH (MPD + fMP4). Note If the container format is FLV, the video codec cannot be set to H.265. Audio transcoding supports the following formats: MP3, MP4, OGG, FLAC, and M4A. Image transcoding supports the GIF and WebP formats. Note If the container format is GIF, the video codec must be set to GIF. If the container format is WebP, the video codec must be set to WebP.	{"Format":"mp4"}
Video	string	No	The video stream settings. The value must be a JSON object. For more information, see Video . Note If you do not specify this parameter, output files do not contain video streams. This parameter is required if you want to retain the video streams.	{"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"}
Audio	string	No	The audio stream settings. The value must be a JSON object. For more information, see Audio . Note If you do not specify this parameter, output files do not contain audio streams. This parameter is required if you want to retain the audio streams.	{"Codec":"H.264","Samplerate":"44100","Bitrate":"500","Channels":"2"}
TransConfig	string	No	The general transcoding settings. The value must be a JSON object. For more information, see TransConfig . If you do not specify this parameter, the default settings are used. This parameter is required if the default settings cannot meet your business requirements.	{"TransMode":"onepass"}
MuxConfig	string	No	The segment settings. The value must be a JSON object. For more information, see MuxConfig . If you do not specify this parameter, media segment files are not generated. This parameter is required if you want to generate media segment files.	{"Segment":{"Duration":"10"}}

Container

Parameter	Type	Required	Description
Format	String	No	The default value of this parameter is MP4. Video transcoding supports the following formats: FLV, MP4, HLS (M3U8 + TS), and MPEG-DASH (MPD + fMP4). Audio transcoding supports the following formats: MP3, MP4, OGG, FLAC, and M4A. Image transcoding supports the GIF and WebP formats. If you set the container format to GIF, the video codec must be set to GIF. If you set the container format to WebP, the video codec must be set to WebP. If you set the container format to FLV, the video codec cannot be set to H.265.

Video

Parameter	Type	Required	Description
Codec	String	No	The video codec. Valid values: H.264, H.265, GIF, and WebP. Default value: H.264.
Profile	String	No	The codec profile. Valid values: baseline, main, and high. Default value: high. A value of baseline specifies that media files are transcoded for mobile devices. A value of main specifies that media files are transcoded for standard-resolution devices. A value of high specifies that media files are transcoded for high-resolution devices. If multiple definitions are available, we recommend that you set this parameter to baseline for the lowest definition to ensure normal playback on low-end devices. Set this parameter to main or high for other definitions. This parameter is valid only if the Codec parameter is set to H.264.
Bitrate	String	No	Valid values: 10 to 50000. Unit: Kbit/s.
Crf	String	No	The constant rate factor. Valid values: 0 to 51. Default value: 26. If you specify this parameter, the setting of the Bitrate parameter becomes invalid.
Width	String	No	The width of the video. Valid values: 128 to 4096. Default value: the width of the input video. Unit: pixel.
Height	String	No	The height of the video. Valid values: 128 to 4096. Default value: the height of the input video. Unit: pixel.
Fps	String	No	The frame rate of the video. Default value: the frame rate of the input file. The value is 60 if the frame rate of the input file exceeds 60. Valid values: 0 to 60.Unit: frames per second.
Gop	String	No	The group of pictures (GOP) size. The GOP size can be the maximum interval of keyframes or the maximum number of frames in a frame group. If you specify the maximum interval of keyframes, the unit (s) is required. Default value: 10s. If you specify the maximum number of frames, the value has no unit. Valid values: 1 to 100000.
Preset	String	No	The preset video algorithm. Valid values: veryfast, fast, medium, slow, and slower. Default value: medium. This parameter is valid only if the Codec parameter is set to H.264.
ScanMode	String	No	The scan mode. Valid values: interlaced and progressive.
Bufsize	String	No	The size of the buffer. Valid values: 1000 to 128000. Default value: 6000. Unit: KB.
Maxrate	String	No	The maximum bitrate of the video. Valid values: 10 to 50000. Unit: Kbit/s.
PixFmt	String	No	The pixel format of the video. Standard pixel formats such as yuv420p and yuvj420p are supported. By default, yuv420p or the pixel format of the input video is used.
Remove	String	No	Specifies whether to delete the video stream. A value of true specifies to delete the video stream. A value of false specifies to retain the video stream. Default value: false.
Crop	String	No	The method for cropping the video. A value of border specifies to automatically detect and crop the black borders. A value in the format of width:height:left:top specifies to crop the video image based on the custom settings. Example: 1280:800:0:140.
Pad	String	No	The black borders to be added to the video. The value must be in the width:height:left:top format. Example: 1280:800:0:140.
LongShortMode	String	No	Specifies whether to enable the auto-rotate screen feature. If this feature is enabled, the width of the output video corresponds to the long side of the input video, which is the height of the input video in portrait mode. The height of the output video corresponds to the short side of the input video, which is the width of the input video in portrait mode. A value of true specifies to enable the auto-rotate screen feature. A value of false specifies to disable the auto-rotate screen feature. Default value: false.

The following table describes the supported combinations of container formats, video codecs, and audio codecs.

Container format	Audio codec	Video codec
FLV	AAC and MP3	H.264
MP4	AAC and MP3	H.264 and H.265
TS	AAC and MP3	H.264 and H.265
M3U8	AAC and MP3	H.264 and H.265
GIF	Not supported	GIF

The following table describes the video stream parameters that are supported by different video codecs. A value of Y specifies that a parameter is supported. A value of N specifies that a parameter is not supported.

Video codec	H.264	H.265	GIF
Profile	Y	N	N
Bitrate	Y	Y	N
Crf	Y	Y	N
Width	Y	Y	Y
Height	Y	Y	Y
Fps	Y	Y	Y
Gop	Y	Y	N
Preset	Y	N	N
ScanMode	Y	Y	Y
Bufsize	Y	Y	N
Maxrate	Y	Y	N
PixFmt	Y	Y	bgr8

Audio

Parameter	Type	Required	Description
Codec	String	No	The audio codec. Valid values: AAC, MP3, VORBIS, and FLAC. Default value: AAC.
Profile	String	No	The codec profile of the audio. Valid values if the Codec parameter is set to AAC: aac_low, aac_he, aac_he_v2, aac_ld, and aac_eld.
Samplerate	String	No	The sampling rate. Valid values: 22050, 32000, 44100, 48000, and 96000. Default value: 44100. Unit: Hz. If the video container format is FLV and the audio codec is MP3, the sampling rate cannot be 32000, 48000, or 96000. If the audio codec is MP3, the sampling rate cannot be 96000.
Bitrate	String	No	The audio bitrate of the output file. Valid values: 8 to 1000. Default value: 128. Unit: Kbit/s.
Channels	String	No	The number of sound channels. Default value: 2. Valid values if the Codec parameter is set to MP3: 1 and 2. Valid values if the Codec parameter is set to AAC: 1, 2, 4, 5, 6, and 8.
Remove	String	No	Specifies whether to delete the audio stream. A value of true specifies to delete the audio stream. A value of false specifies to retain the audio stream. Default value: false.

The following table describes the supported combinations of audio codecs and container formats.

Container format	Audio codec
MP3	MP3
MP4	AAC
OGG	VORBIS and FLAC
FLAC	FLAC

TransConfig

Parameter	Type	Required	Description
TransMode	String	No	The transcoding mode. Valid values: onepass, twopass, and CBR. Default value: onepass.
AdjDarMethod	String	No	The method of resolution adjustment. Valid values: rescale, crop, pad, and none. Default value: none.
IsCheckReso	String	No	Specifies whether to check the resolution. If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, the resolution of the input file is retained after transcoding. A value of true specifies to check the resolution. A value of false specifies not to check the resolution. Default value: false.
IsCheckResoFail	String	No	Specifies whether to check the resolution. If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, an error that indicates a transcoding failure is returned. A value of true specifies to check the resolution. A value of false specifies not to check the resolution. Default value: false.
IsCheckVideoBitrate	String	No	Specifies whether to check the video bitrate. If this feature is enabled and the system detects that the video bitrate of the output file is greater than that of the input file, the video bitrate of the input file is retained after transcoding. A value of true specifies to check the video bitrate. A value of false specifies not to check the video bitrate. Default value: false.
IsCheckAudioBitrate	String	No	Specifies whether to check the audio bitrate. If this feature is enabled and the system detects that the audio bitrate of the output file is greater than that of the input file, the audio bitrate of the input file is retained after transcoding. A value of true specifies to check the audio bitrate. A value of false specifies not to check the audio bitrate. Default value: false.
IsCheckAudioBitrateFail	String	No	Specifies whether to check the audio bitrate. If this feature is enabled and the system detects that the bitrate of the output audio is higher than that of the input audio, the input audio is not transcoded. A value of true specifies to check the audio bitrate. A value of false specifies not to check the audio bitrate. Default value: false. This parameter takes precedence over the IsCheckAudioBitrate parameter.
IsCheckVideoBitrateFail	String	No	Specifies whether to check the video bitrate. If this feature is enabled and the system detects that the bitrate of the output video is higher than that of the input video, the input video is not transcoded. A value of true specifies to check the video bitrate. A value of false specifies not to check the video bitrate. Default value: false. This parameter takes precedence over the IsCheckVideoBitrate parameter.

MuxConfig

Parameter	Type	Required	Description
Segment	String	No	The segment settings. The value must be a JSON object. For more information, see the following section.

Segment

Parameter	Type	Required	Description
Duration	String	No	The length of the segment. The value must be an integer. Unit: seconds. Valid values: 1 to 60. Default value: 10.
ForceSegTime	String	No	The points in time at which you want to segment the media file. You can specify up to 10 points in time. Separate the points in time with commas (,). The points in time can be accurate to three decimal places. Unit: seconds. For example, if you set this parameter to 23,55,60, the media file will be segmented at the 23rd, 55th, and 60th seconds.

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
RequestId	string	The ID of the request.	FA258E67-09B8-4EAA-8F33-BA567834A2C3
Template	object	The details of the transcoding template.
Video	object	The video codec configurations.
Bufsize	string	The size of the buffer. Default value: 6000. Unit: KB.	6000
LongShortMode	string	Indicates whether the auto-rotate screen feature is enabled. Default value: false. Valid values: true: The auto-rotate screen feature is enabled. false: The auto-rotate screen feature is disabled. Note If this feature is enabled, the width of the output video corresponds to the long side of the input video, which is the height of the input video in portrait mode. The height of the output video corresponds to the short side of the input video, which is the width of the input video in portrait mode.	false
Degrain	string	The level of quality control on the video.	10
BitrateBnd	object	The bitrate range of the video.
Max	string	The maximum bitrate.	1500
Min	string	The minimum bitrate.	800
PixFmt	string	The pixel format. Standard pixel formats such as yuv420p and yuvj420p are supported. The default pixel format can be yuv420p or the pixel format of the input video.	yuv420p
Pad	string	The black borders to be added to the video. The value is in the width:height:left:top format.	1280:800:0:140
Codec	string	The video codec. Valid values: H.264, H.265, GIF, and WebP. Default value: H.264.	H.264
Height	string	The height of the video. Unit: pixel. Default value: the height of the input video.	800
Qscale	string	The level of the independent denoising algorithm.	1
Crop	string	The method of video cropping. Valid values: border: automatically detects and removes borders. Value in the format of width:height:left:top: crops the video image based on the custom settings. Example: 1280:800:0:140.	border
Bitrate	string	The bitrate of the output video. Unit: Kbit/s.	500
Maxrate	string	The maximum bitrate of the video. Unit: Kbit/s.	500
MaxFps	string	The maximum frame rate.	60
Profile	string	The codec profile. baseline: suitable for mobile devices main: suitable for standard-definition devices high: suitable for high-definition devices Default value: high. If multiple definitions are available, we recommend that you set this parameter to baseline for the lowest definition to ensure normal playback on low-end devices. Set this parameter to main or high for other definitions. Note This parameter is valid only if the Codec parameter is set to H.264.	high
Crf	string	The constant rate factor. Default value if the video codec is set to H.264: 23. Default value if the video codec is set to H.265: 26. Note If this parameter is specified, the setting of the Bitrate parameter becomes invalid.	15
Remove	string	Indicates whether the video stream is deleted. true: The video stream is deleted. false: The video stream is retained. Default value: false.	false
Gop	string	The GOP size. The GOP size can be the maximum interval of keyframes or the maximum number of frames in a frame group. If the maximum interval is specified, the value contains the unit (s). If the maximum number of frames is specified, the value does not contain a unit. Default value: 10s.	10s
Width	string	The width of the video. Default value: the width of the input video.**** Unit: pixel.	256
Fps	string	The frame rate. Default value: the frame rate of the input file. The value is 60 if the frame rate of the input file exceeds 60. Unit: frames per second.	25
Preset	string	The preset video algorithm. Default value: medium. Valid values: veryfast fast medium slow slower Note This parameter is valid only if the Codec parameter is set to H.264.	fast
ScanMode	string	The scan mode. Valid values: interlaced progressive	interlaced
ResoPriority	string	The policy of resolution adjustment.	0
Hdr2sdr	string	Indicates whether the HDR2SDR conversion feature is enabled. If this feature is enabled, high dynamic range (HDR) videos are transcoded to standard dynamic range (SDR) videos.	true
NarrowBand	object	The Narrowband HD settings.
Version	string	The Narrowband HD version. Only 1.0 may be returned.	1.0
Abrmax	float	The upper limit of the dynamic bitrate. If this parameter is set, the average bitrate is in the range of (0, 1000000].	3000
MaxAbrRatio	float	The maximum ratio of the upper limit of dynamic bitrate. If this parameter is set, the value of Abrmax does not exceed x times of the source video bitrate. Valid values: (0,1.0].	1.0
TransConfig	object	The general transcoding settings.
IsCheckAudioBitrate	string	Indicates whether the audio bitrate is checked. If this feature is enabled and the system detects that the audio bitrate of the output file is greater than that of the input file, the audio bitrate of the input file is retained after transcoding. true: The audio bitrate is checked. false: The audio bitrate is not checked. Default value: false.	true
TransMode	string	The transcoding mode. Valid values: onepass twopass CBR Default value: onepass.	onepass
IsCheckReso	string	Indicates whether the resolution is checked. true: The resolution is checked. false: The resolution is not checked. Default value: false. Note If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, the resolution of the input file is retained after transcoding.	true
IsCheckVideoBitrateFail	string	Indicates whether the video bitrate is checked. If this feature is enabled and the system detects that the video bitrate of the output file is higher than that of the input file, the input file is not transcoded. This parameter has a higher priority than the IsCheckVideoBitrate parameter. true: The video bitrate is checked. In this case, if the video bitrate of the output file is higher than that of the input file, the input file is not transcoded. false: The video bitrate is not checked. Default value: false.	true
AdjDarMethod	string	The method of resolution adjustment. Default value: none. Valid values: rescale: The input video is rescaled. crop: The input video is cropped. none: No change is made.	rescale
IsCheckVideoBitrate	string	Indicates whether the video bitrate is checked. true: The video bitrate is checked. false: The video bitrate is not checked. Default value: false. Note If this feature is enabled and the system detects that the video bitrate of the output file is greater than that of the input file, the video bitrate of the input file is retained after transcoding.	true
IsCheckResoFail	string	Indicates whether the resolution is checked. true: The resolution is checked. false: The resolution is not checked. Default value: false. Note If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, an error that indicates a transcoding failure is returned.	true
IsCheckAudioBitrateFail	string	Indicates whether the audio bitrate is checked. If this feature is enabled and the system detects that the audio bitrate of the output file is higher than that of the input file, the input file is not transcoded. This parameter has a higher priority than the IsCheckAudioBitrate parameter. Valid values: true: The audio bitrate is checked. In this case, if the audio bitrate of the output file is higher than that of the input file, the input file is not transcoded. false: The audio bitrate is not checked. Default value: false.	true
State	string	The status of the template. Valid values: Normal: The template is normal. Deleted: The template is deleted.	Normal
MuxConfig	object	The transmuxing settings.
Webp	object	The transmuxing settings for WebP.
Loop	string	The loop count.	0
Gif	object	The transmuxing settings for GIF.
FinalDelay	string	The duration for which the final frame is paused. Unit: centiseconds.	0
DitherMode	string	The color dithering algorithm of the palette. Valid values: sierra and bayer.	sierra
Loop	string	The loop count.	0
IsCustomPalette	string	Indicates whether the custom palette is used.	false
Segment	object	The segment settings.
Duration	string	The length of the segment. Unit: seconds.	10
Name	string	The name of the transcoding template.	mps-example
Audio	object	The audio codec configurations.
Profile	string	The codec profile of the audio. Valid values if the Codec parameter is set to AAC: aac_low aac_he aac_he_v2 aac_ld aac_eld	aac_low
Remove	string	Indicates whether the audio stream is deleted. true: The audio stream is deleted. false: The audio stream is retained. Default value: false.	true
Codec	string	The audio codec format. Default value: aac. Valid values: aac mp3 vorbis flac	aac
Samplerate	string	The sampling rate. Unit: Hz. Default value: 44100.	44100
Qscale	string	The level of the independent denoising algorithm.	5
Channels	string	The number of sound channels. Default value: 2.	2
Volume	object	The volume control configurations
Method	string	The volume adjustment method. Valid values: auto: The volume is automatically adjusted. dynamic: The volume is dynamically adjusted. linear: The volume is linearly adjusted.	auto
Level	string	The volume adjustment range. Default value: -20. Unit: dB.	-20
IntegratedLoudnessTarget	string	The output volume. This parameter takes effect only when the value of Method is dynamic. Unit: dB. Valid values: [-70,-5]. Default value: -6.	-6
TruePeak	string	The peak volume. This parameter takes effect only when the value of Method is dynamic. Unit: dB. Valid values: [-9,0]. Default value: -1.	0
LoudnessRangeTarget	string	The range of the volume relative to the output volume. This parameter takes effect only when the value of Method is dynamic. Unit: dB. Valid values: [1,20]. Default value: 8.	8
PeakLevel	string	The volume adjustment coefficient. This parameter takes effect only when the value of Method is adaptive. Valid values: [0,1]. Default value: 0.9.	0.9
Bitrate	string	The audio bitrate of the output file. Unit: Kbit/s. Default value: 128.	500
Id	string	The ID of the transcoding template. We recommend that you keep this ID for subsequent operation calls.	16f01ad6175e4230ac42bb5182cd****
Container	object	The container format settings.
Format	string	The container format.	mp4

Examples

Sample success responses

JSONformat

{
  "RequestId": "FA258E67-09B8-4EAA-8F33-BA567834A2C3",
  "Template": {
    "Video": {
      "Bufsize": "6000",
      "LongShortMode": "false",
      "Degrain": "10",
      "BitrateBnd": {
        "Max": "1500",
        "Min": "800"
      },
      "PixFmt": "yuv420p",
      "Pad": "1280:800:0:140",
      "Codec": "H.264",
      "Height": "800",
      "Qscale": "1",
      "Crop": "border",
      "Bitrate": "500",
      "Maxrate": "500",
      "MaxFps": "60",
      "Profile": "high",
      "Crf": "15",
      "Remove": "false",
      "Gop": "10s",
      "Width": "256",
      "Fps": "25",
      "Preset": "fast",
      "ScanMode": "interlaced",
      "ResoPriority": "0",
      "Hdr2sdr": "true",
      "NarrowBand": {
        "Version": "1.0",
        "Abrmax": 3000,
        "MaxAbrRatio": 1
      }
    },
    "TransConfig": {
      "IsCheckAudioBitrate": "true",
      "TransMode": "onepass",
      "IsCheckReso": "true",
      "IsCheckVideoBitrateFail": "true",
      "AdjDarMethod": "rescale",
      "IsCheckVideoBitrate": "true",
      "IsCheckResoFail": "true",
      "IsCheckAudioBitrateFail": "true"
    },
    "State": "Normal",
    "MuxConfig": {
      "Webp": {
        "Loop": "0"
      },
      "Gif": {
        "FinalDelay": "0",
        "DitherMode": "sierra",
        "Loop": "0",
        "IsCustomPalette": "false"
      },
      "Segment": {
        "Duration": "10"
      }
    },
    "Name": "mps-example",
    "Audio": {
      "Profile": "aac_low",
      "Remove": "true",
      "Codec": "aac",
      "Samplerate": "44100",
      "Qscale": "5",
      "Channels": "2",
      "Volume": {
        "Method": "auto",
        "Level": "-20",
        "IntegratedLoudnessTarget": "-6",
        "TruePeak": "0",
        "LoudnessRangeTarget": "8",
        "PeakLevel": "0.9"
      },
      "Bitrate": "500"
    },
    "Id": "16f01ad6175e4230ac42bb5182cd****",
    "Container": {
      "Format": "mp4"
    }
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-03-13	The response structure of the API has changed	View Change Details
2024-01-04	The response structure of the API has changed	View Change Details