All Products
Search
Document Center

ApsaraVideo Media Processing:AddTemplate

Last Updated:Feb 06, 2024

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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
NamestringYes

The name of the transcoding template. The name can be up to 128 bytes in length.

mps-example
ContainerstringNo

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"}
VideostringNo

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"}
AudiostringNo

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"}
TransConfigstringNo

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"}
MuxConfigstringNo

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

ParameterTypeRequiredDescription
FormatStringNoThe 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

ParameterTypeRequiredDescription
CodecStringNoThe video codec. Valid values: H.264, H.265, GIF, and WebP. Default value: H.264.
ProfileStringNoThe 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.
BitrateStringNoValid values: 10 to 50000. Unit: Kbit/s.
CrfStringNoThe constant rate factor. Valid values: 0 to 51. Default value: 26. If you specify this parameter, the setting of the Bitrate parameter becomes invalid.
WidthStringNoThe width of the video. Valid values: 128 to 4096. Default value: the width of the input video. Unit: pixel.
HeightStringNoThe height of the video. Valid values: 128 to 4096. Default value: the height of the input video. Unit: pixel.
FpsStringNoThe 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.
GopStringNoThe 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.
PresetStringNoThe 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.
ScanModeStringNoThe scan mode. Valid values: interlaced and progressive.
BufsizeStringNoThe size of the buffer. Valid values: 1000 to 128000. Default value: 6000. Unit: KB.
MaxrateStringNoThe maximum bitrate of the video. Valid values: 10 to 50000. Unit: Kbit/s.
PixFmtStringNoThe 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.
RemoveStringNoSpecifies 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.
CropStringNoThe 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.
PadStringNoThe black borders to be added to the video. The value must be in the width:height:left:top format. Example: 1280:800:0:140.
LongShortModeStringNoSpecifies 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 formatAudio codecVideo codec
FLVAAC and MP3H.264
MP4AAC and MP3H.264 and H.265
TSAAC and MP3H.264 and H.265
M3U8AAC and MP3H.264 and H.265
GIFNot supportedGIF

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 codecH.264H.265GIF
ProfileYNN
BitrateYYN
CrfYYN
WidthYYY
HeightYYY
FpsYYY
GopYYN
PresetYNN
ScanModeYYY
BufsizeYYN
MaxrateYYN
PixFmtYYbgr8

Audio

ParameterTypeRequiredDescription
CodecStringNoThe audio codec. Valid values: AAC, MP3, VORBIS, and FLAC. Default value: AAC.
ProfileStringNoThe 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.
SamplerateStringNoThe 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.
BitrateStringNoThe audio bitrate of the output file. Valid values: 8 to 1000. Default value: 128. Unit: Kbit/s.
ChannelsStringNoThe 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.
RemoveStringNoSpecifies 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 formatAudio codec
MP3MP3
MP4AAC
OGGVORBIS and FLAC
FLACFLAC

TransConfig

ParameterTypeRequiredDescription
TransModeStringNoThe transcoding mode. Valid values: onepass, twopass, and CBR. Default value: onepass.
AdjDarMethodStringNoThe method of resolution adjustment. Valid values: rescale, crop, pad, and none. Default value: none.
IsCheckResoStringNoSpecifies 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.
IsCheckResoFailStringNoSpecifies 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.
IsCheckVideoBitrateStringNoSpecifies 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.
IsCheckAudioBitrateStringNoSpecifies 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.
IsCheckAudioBitrateFailStringNoSpecifies 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.
IsCheckVideoBitrateFailStringNoSpecifies 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

ParameterTypeRequiredDescription
SegmentStringNoThe segment settings. The value must be a JSON object. For more information, see the following section.

Segment

ParameterTypeRequiredDescription
DurationStringNoThe length of the segment. The value must be an integer. Unit: seconds. Valid values: 1 to 60. Default value: 10.
ForceSegTimeStringNoThe 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

ParameterTypeDescriptionExample
object

The response parameters.

RequestIdstring

The ID of the request.

FA258E67-09B8-4EAA-8F33-BA567834A2C3
Templateobject

The details of the transcoding template.

Videoobject

The video codec configurations.

Bufsizestring

The size of the buffer.

  • Default value: 6000.
  • Unit: KB.
6000
LongShortModestring

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
Degrainstring

The level of quality control on the video.

10
BitrateBndobject

The bitrate range of the video.

Maxstring

The maximum bitrate.

1500
Minstring

The minimum bitrate.

800
PixFmtstring

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
Padstring

The black borders to be added to the video. The value is in the width:height:left:top format.

1280:800:0:140
Codecstring

The video codec. Valid values: H.264, H.265, GIF, and WebP. Default value: H.264.

H.264
Heightstring

The height of the video.

  • Unit: pixel.
  • Default value: the height of the input video.
800
Qscalestring

The level of the independent denoising algorithm.

1
Cropstring

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
Bitratestring

The bitrate of the output video. Unit: Kbit/s.

500
Maxratestring

The maximum bitrate of the video. Unit: Kbit/s.

500
MaxFpsstring

The maximum frame rate.

60
Profilestring

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
Crfstring

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
Removestring

Indicates whether the video stream is deleted.

  • true: The video stream is deleted.
  • false: The video stream is retained.
  • Default value: false.
false
Gopstring

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
Widthstring

The width of the video.

  • Default value: the width of the input video.****
  • Unit: pixel.
256
Fpsstring

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
Presetstring

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
ScanModestring

The scan mode. Valid values:

  • interlaced
  • progressive
interlaced
ResoPrioritystring

The policy of resolution adjustment.

0
TransConfigobject

The general transcoding settings.

IsCheckAudioBitratestring

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
TransModestring

The transcoding mode. Valid values:

  • onepass
  • twopass
  • CBR
  • Default value: onepass.
onepass
IsCheckResostring

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
IsCheckVideoBitrateFailstring

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
AdjDarMethodstring

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
IsCheckVideoBitratestring

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
IsCheckResoFailstring

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
IsCheckAudioBitrateFailstring

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
Statestring

The status of the template. Valid values:

  • Normal: The template is normal.
  • Deleted: The template is deleted.
Narmal
MuxConfigobject

The transmuxing settings.

Webpobject

The transmuxing settings for WebP.

Loopstring

The loop count.

0
Gifobject

The transmuxing settings for GIF.

FinalDelaystring

The duration for which the final frame is paused. Unit: centiseconds.

0
DitherModestring

The color dithering algorithm of the palette. Valid values: sierra and bayer.

sierra
Loopstring

The loop count.

0
IsCustomPalettestring

Indicates whether the custom palette is used.

false
Segmentobject

The segment settings.

Durationstring

The length of the segment. Unit: seconds.

10
Namestring

The name of the transcoding template.

mps-example
Audioobject

The audio codec configurations.

Profilestring

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
Removestring

Indicates whether the audio stream is deleted.

  • true: The audio stream is deleted.
  • false: The audio stream is retained.
  • Default value: false.
true
Codecstring

The audio codec format. Default value: aac. Valid values:

  • aac
  • mp3
  • vorbis
  • flac
aac
Sampleratestring

The sampling rate.

  • Unit: Hz.
  • Default value: 44100.
44100
Qscalestring

The level of the independent denoising algorithm.

5
Channelsstring

The number of sound channels. Default value: 2.

2
Volumeobject

The volume control configurations

Methodstring

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
Levelstring

The volume adjustment range.

  • Default value: -20.
  • Unit: dB.
-20
IntegratedLoudnessTargetstring

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
TruePeakstring

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
LoudnessRangeTargetstring

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
PeakLevelstring

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
Bitratestring

The audio bitrate of the output file.

  • Unit: Kbit/s.
  • Default value: 128.
500
Idstring

The ID of the transcoding template. We recommend that you keep this ID for subsequent operation calls.

16f01ad6175e4230ac42bb5182cd****
Containerobject

The container format settings.

Formatstring

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": ""
    },
    "TransConfig": {
      "IsCheckAudioBitrate": "true",
      "TransMode": "onepass",
      "IsCheckReso": "true",
      "IsCheckVideoBitrateFail": "true",
      "AdjDarMethod": "rescale",
      "IsCheckVideoBitrate": "true",
      "IsCheckResoFail": "true",
      "IsCheckAudioBitrateFail": "true"
    },
    "State": "Narmal",
    "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 timeSummary of changesOperation
2024-01-04The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.