Creates a custom transcoding template.

Usage notes

You can call this operation to set the parameters that are related to the container, audio streams, and video streams. For some parameters, if you do not specify them, streams that are generated by using the template do not have the corresponding settings.

Limits on QPS

You can call this operation up to 100 times per second per account. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the 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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes AddTemplate

The operation that you want to perform. Set the value to AddTemplate.

Name String Yes mps-example

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

Container String No null

The container configuration. The value must be a JSON object and contains the Format parameter. If you do not configure the container, the transcoded media file is in MP4 format by default. If you want to use the transcoding template to generate media files in other formats, this parameter is required. For more information, see the Parameter nested under the Container parameter section of this topic.

  • Default value of the Format parameter: mp4.
  • Video formats include 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 formats include MP3, MP4, Ogg, FLAC, and M4A
  • Image formats include GIF and WebP.
    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.
Video String No null

The video stream configuration. The value must be a JSON object. For more information, see the Parameters nested under the Video parameter section of this topic.

Note If you do not set this parameter, output files do not contain video streams. If you need to retain the video streams, this parameter is required.
Audio String No null

The audio stream configuration. The value must be a JSON object. For more information, see the Parameters nested under the Audio parameter section of this topic.

Note If you do not set this parameter, output files do not contain audio streams. If you need to retain the audio streams, this parameter is required.
TransConfig String No null

The general transcoding configuration. The value must be a JSON object. For more information, see the Parameters nested under the TransConfig parameter section of this topic. If you do not set this parameter, the default settings of this parameter are used. If the default settings cannot meet your transcoding needs, set the parameters nested under the TransConfig parameter as required.

MuxConfig String No null

The segment configuration. The value must be a JSON object. For more information, see the Parameters nested under the MuxConfig parameter section of this topic. If you do not set this parameter, media segment files are not generated. If you want to generate media segment files, this parameter is required.

Parameter nested under the Container parameter

Parameter

Type

Required

Description

Format

String

No

Default value: mp4. Video formats include FLV, MP4, HLS (M3U8 + TS), and MPEG-DASH (MPD + fMP4) Audio formats include MP3, MP4, Ogg, FLAC, and M4A Image formats include GIF and WebP. If you set the container format to GIF or WebP, the video codec must be respectively set to GIF or WebP. If you set the container format to FLV, the video codec cannot be set to H.265.

Parameters nested under the Video parameter

Parameter

Type

Required

Description

Codec

String

No

The video codec. Valid video codecs: H.264, H.265, GIF, and WebP. Default video codec: 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 exist, 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 when the video codec is set to H.264.

Bitrate

String

No

The bitrate. Valid values: 10 to 50000. Unit: Kbit/s.

Crf

String

No

The constant rate factor. Valid values: 0 to 51. Default value: 26. If this parameter is specified, the setting of the Bitrate parameter becomes invalid.

Width

String

No

The width of the video. Default value: the width of the input video. Valid values: 128 to 4096. Unit: pixel.

Height

String

No

The height of the video. Default value: the height of the input video. Valid values: 128 to 4096. 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,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 when the video codec 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,128000]. Default value: 6000. Unit: KB.

Maxrate

String

No

The maximum video bitrate. Valid values: [10,50000]. Unit: Kbit/s.

PixFmt

String

No

The pixel format for video color encoding. Standard pixel formats such as yuv420p and yuvj420p are supported. The default pixel format can be yuv420p or the original color format.

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 of video cropping. 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 setting. Example: 1280:800:0:140.

Pad

String

No

The black borders to be added to the video. Format: width:height:left:top. 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 feature. A value of false specifies to disable the 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

N/A

GIF

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

Video stream parameter/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

Y (only BGR8)

Parameters nested under the Audio parameter

Parameter

Type

Required

Description

Codec

String

No

The audio codec. Valid audio codecs: AAC, MP3, VORBIS, and FLAC. Default audio codec: AAC.

Profile

String

No

The codec profile of the audio. Valid values when the audio codec 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, you cannot set this parameter to 32000, 48000, or 96000. If the audio codec is MP3, you cannot set this parameter to 96000.

Bitrate

String

No

The audio bitrate of the output file. Valid values:[8,1000]. Default value: 128. Unit: Kbit/s.

Channels

String

No

The number of sound channels. Default value: 2. Valid values when the audio codec is set to MP3: 1 and 2. Valid values when the audio codec 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

Parameters nested under the TransConfig parameter

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 audio bitrate of the output file is higher than that of the input file, the input file 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 has a higher priority than the IsCheckAudioBitrate parameter.

IsCheckVideoBitrateFail

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 higher than that of the input file, the input file 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 has a higher priority than the IsCheckVideoBitrate parameter.

Parameters nested under the MuxConfig parameter

Parameter

Type

Required

Description

Segment

String

No

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

Parameters nested under the Segment parameter

Parameter

Type

Required

Description

Duration

String

No

The length of the segment. The value must be an integer. Unit: seconds. Valid values: [1,60]. Default value: 10.

ForceSegTime

String

No

Specifies the time points at which you want to segment the media file. You can specify up to 10 time points. Separate the time points with commas (,). The time points 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 Example Description
RequestId String FA258E67-09B8-4EAA-8F33-BA567834A2C3

The ID of the request.

Template Object

The details of the transcoding template.

Video Object

The video codec configuration.

Bufsize String 6000

The size of the buffer.

  • Default value: 6000.
  • Unit: KB.
LongShortMode String false

Indicates whether to enable the auto-rotate screen feature. 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.
Degrain String 10

The level of quality control on the video.

BitrateBnd Object

The bitrate range of the video.

Max String 1500

The maximum bitrate.

Min String 800

The minimum bitrate.

PixFmt String yuv420p

The pixel format for video color encoding. Standard pixel formats such as yuv420p and yuvj420p are supported. The default pixel format can be yuv420p or the original color format.

Pad String 1280:800:0:140

The black borders to be added to the video. Format: width:height:left:top.

Codec String H.264

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

Height String 800

The height of the video.

  • Unit: pixel.
  • Default value: the height of the input video.
Qscale String 1

The level of the independent denoising algorithm.

Crop String border

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 setting. Example: 1280:800:0:140.
Bitrate String 500

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

Maxrate String 500

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

MaxFps String 60

The maximum frame rate.

Profile String high

The codec profile. Valid values:

  • baseline: suitable for mobile devices
  • main: suitable for standard-definition devices
  • high: suitable for high-definition devices
  • Default value: high.

If multiple definitions exist, 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 when the video codec is set to H.264.
Crf String 15

The constant rate factor. Default value when the video codec is set to H.264: 23. Default value when the video codec is set to H.265: 26.

Note If this parameter is specified, the setting of the Bitrate parameter becomes invalid.
Remove String false

Indicates whether to delete the video stream.

  • true: The video stream is deleted.
  • false: The video stream is retained.
  • Default value: false.
Gop String 10s

The GOP size. The GOP size can be the maximum interval of keyframes or the maximum number of frames in a frame group. If you specified the maximum interval, the value contains the unit (s). If you specified the maximum number of frames, the value does not contain a unit. Default value: 10s.

Width String 256

The width of the video.

  • Default value: the width of the input video.
  • Unit: pixel.
Fps String 25

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. Unit: frames per second.

Preset String fast

The preset video algorithm. Default value: medium. Valid values:

  • veryfast
  • fast
  • medium
  • slow
  • slower
Note This parameter is valid only when the video codec is set to H.264.
ScanMode String interlaced

The scan mode. Valid values:

  • interlaced
  • progressive
ResoPriority String 0

The policy of resolution adjustment.

TransConfig Object

The general transcoding configuration.

IsCheckAudioBitrate String true

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

  • true: The audio bitrate is checked.
  • false: The audio bitrate is not checked.
  • Default value: false.
TransMode String onepass

The transcoding mode. Valid values:

  • onepass
  • twopass
  • CBR
  • Default value: onepass.
IsCheckReso String true

Indicates whether to check the resolution.

  • 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.
IsCheckVideoBitrateFail String true

If the video bitrate of the output file is found to be greater than that of the input file, this parameter has a higher priority than the IsCheckVideoBitrate parameter. Valid values:

  • true: The video bitrate is checked. 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.
AdjDarMethod String rescale

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.
IsCheckVideoBitrate String true

Indicates whether to check the video bitrate.

  • 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.
IsCheckResoFail String true

Indicates whether to check the resolution.

  • 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.
IsCheckAudioBitrateFail String true

Indicates whether to check the audio bitrate. If the bitrate of the output audio is greater than that of the input audio, this parameter has a higher priority than the IsCheckAudioBitrate parameter.

  • true: The audio bitrate is checked. If the bitrate of the output audio is greater than that of the input audio, the input file is not transcoded.
  • false: The audio bitrate is not checked.
  • Default value: false.
State String Narmal

The status of the template.

  • Normal: The template is normal.
  • Deleted: The template is deleted.
MuxConfig Object

The transmuxing configuration.

Webp Object

The transmuxing configuration for WebP.

Loop String 0

The loop count.

Gif Object

The transmuxing configuration for GIF.

FinalDelay String 0

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

DitherMode String sierra

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

Loop String 0

The loop count.

IsCustomPalette String false

Indicates whether the custom palette is used.

Segment Object

The segment configuration.

Duration String 10

The length of the segment. Unit: seconds.

Name String mps-example

The name of the template.

Audio Object

The audio codec configuration.

Profile String aac_low

The codec profile of the audio. Valid values when the audio codec is set to AAC:

  • aac_low
  • aac_he
  • aac_he_v2
  • aac_ld
  • aac_eld
Remove String true

Indicates whether to delete the audio stream.

  • true: The audio stream is deleted.
  • false: The audio stream is retained.
  • Default value: false.
Codec String aac

The audio codec. Default audio codec: AAC. Valid audio codecs:

  • AAC
  • MP3
  • VORBIS
  • FLAC
Samplerate String 44100

The sampling rate.

  • Unit: Hz.
  • Default value: 44100.
Qscale String 5

The level of the independent denoising algorithm.

Channels String 2

The number of sound channels. Default value: 2.

Volume Object

The details of the volume.

Method String auto

The volume adjustment method. Valid values:

  • auto: The volume is automatically adjusted.
  • dynamic: The volume is dynamically adjusted.
  • linear: The volume is linearly adjusted.
Level String -20

The volume adjustment range.

  • Default value: -20.
  • Unit: dB.
Bitrate String 500

The audio bitrate of the output file.

  • Unit: Kbit/s.
  • Default value: 128.
Id String 16f01ad6175e4230ac42bb5182cd****

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

Container Object

The container configuration.

Format String mp4

The container format.

Examples

Sample requests

http(s)://mts.cn-hangzhou.aliyuncs.com/?Action=AddTemplate
&Name=mps-example
&Container={"Format":"mp4"}
&Video={"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"}
&Audio={"Codec":"H.264","Samplerate":"44100","Bitrate":"500","Channels":"2"}
&TransConfig={"TransMode":"onepass"}
&MuxConfig={"Segment":{"Duration":"10"}}
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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"
    },
    "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"
      },
      "Bitrate" : "500"
    },
    "Id" : "16f01ad6175e4230ac42bb5182cd****",
    "Container" : {
      "Format" : "mp4"
    }
  }
}

Error codes

For a list of error codes, visit the API Error Center.