调用AddTemplate新增自定义转码模板。

使用说明

本接口参数中包含容器信息、视频和音频流等设置,如果相应部分不做设置,则使用模板转出来的码流中也不会包含相应的信息。

QPS限制

本接口的单用户QPS限制为100次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。更多信息,请参见QPS限制

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String AddTemplate

操作接口名,系统规定参数,取值:AddTemplate

Name String mps-example

模板名称。最大长度128字节。

Container String {"Format":"mp4"}

容器,JSON对象,其中包含参数为Format(容器格式)。不设置Container参数则转码输出默认为mp4格式,如需其他格式则必须设置此对象。更多信息请参见Container详情

  • 默认值:mp4。
  • 视频转码支持flv、mp4、HLS(m3u8+ts)、MPEG-DASH(MPD+fMP4)。
说明 容器格式为flv时,Video Codec不能设置为H.265。
  • 音频转码支持mp3、mp4、ogg、flac、m4a。
  • 图片支持gif、WEBP。
    说明
    • 容器格式为gif时,VideoCodec设置只能设置为GIF。
      • 容器格式为webp时,Video Codec设置只能设置为WEBP。
Video String {"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"}

视频流配置。JSON对象,更多信息请参见Video详情

说明 不设置Video参数则转码输出不包括视频流;如需保留视频流则必须设置此对象。
Audio String {"Codec":"H.264","Samplerate":"44100","Bitrate":"500","Channels":"2"}

音频流配置。JSON对象,详情参见Audio详情

说明 不设置Audio参数则转码输出不包括音频流;如需保留音频流则必须设置此对象。
TransConfig String {"TransMode":"onepass"}

转码通用配置。JSON对象,详情参见TransConfig详情。不设置TransConfig参数则转码配置全部为默认值,如默认值不能满足您的转码需求则必须按需设置此对象。

MuxConfig String {"Segment":{"Duration":"10"}}

切片配置字段。JSON对象,详情参见MuxConfig详情。不设置MuxConfig参数则转码输出不分片,如需分片则必须设置此对象。

JSON对象Container详情

参数

值类型

是否必选

描述

Format

String

默认值:mp4。视频转码支持flv、mp4、HLS(m3u8+ts)、MPEG-DASH(MPD+fMP4)。音频转码支持mp3、mp4、ogg、flac、m4a。图片支持gif、WEBP。容器格式为gif时,Video Codec设置只能设置为GIF,容器格式为webp时,Video Codec设置只能设置为WEBP,容器格式为flv时,Video Codec不能设置为H.265。

JSON对象Video详情

参数

值类型

是否必选

描述

Codec

String

编解码格式。支持H.264、H.265、GIF、WEBP,默认值:H.264。

Profile

String

编码级别。支持baseline(适合移动设备)、main(适合标准分辨率设备)、high(适合高分辨率设备),默认值:high。最佳实践:如果您有多个清晰度,建议最低清晰度配成baseline,以保证最低端设备可播放。其他清晰度配置为main或high。目前仅H.264支持此参数。

Bitrate

String

值范围:10~50000,单位:Kbps。

Crf

String

码率-质量控制因子。值范围:0~51,默认值:26。如果设置了Crf,则Bitrate的设置失效。

Width

String

宽。默认值:视频原始宽度,值范围:128~4096,单位:px。

Height

String

高。默认值:视频原始高度,值范围:128~4096,单位:px。

Fps

String

帧率。默认值:取输入文件帧率。当输入文件帧率超过60时取60。值范围:0~60。单位:fps。

Gop

String

关键帧间最大时间间隔或者最大帧数。最大时间间隔时,必传单位s。默认值:10s。最大帧数时,无单位,值范围:1~100000。

Preset

String

视频算法器预置。支持veryfast(超快)、fast(快)、medium(中等)、slow(慢)、slower(超慢)。默认值:medium。目前仅H.264支持此参数。

ScanMode

String

扫描模式。支持interlaced、progressive。

Bufsize

String

缓冲区大小。值范围:[1000,128000],默认值:6000,单位:Kb。

Maxrate

String

视频码率峰值。值范围[10,50000],单位Kbps。

PixFmt

String

视频颜色格式。范围yuv420p,yuvj420p等标准颜色格式。默认值:yuv420p或原始颜色格式。

Remove

String

是否删除视频流。true表示删除,false表示保留,默认值:false。

Crop

String

视频画面裁切。支持2种方式:自动检测黑边并裁切,设置为“border”。自定义裁切,参数格式:width:height:left:top。示例:1280:800:0:140。

Pad

String

视频贴黑边。参数格式:width:height:left:top。示例:1280:800:0:140 。

LongShortMode

String

是否开启横竖屏自适应(即:长短边模式)。转码输出的宽对应输入片源的长边(竖屏为片源的高),高对应输入视频的短边(竖屏为片源的宽),true表示开启,false表示关闭,默认值:false。

以下表格显示视频转码编解码格式与容器格式的组合支持情况:

Container

Audio Codecs

Video Codecs

flv

AAC、MP3

H.264

mp4

AAC、MP3

H.264、H.265

ts

AAC、MP3

H.264、H.265

m3u8

AAC、MP3

H.264、H.265

gif

不支持

GIF

以下表格显示视频编解码格式与视频流配置参数的组合支持情况:

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

JSON对象Audio详情

参数

值类型

是否必选

描述

Codec

String

音频编解码格式,AAC、MP3、VORBIS、FLAC。默认值:AAC。

Profile

String

音频编码预置。当Codec为AAC时,范围aac_low、aac_he、aac_he_v2、aac_ld、aac_eld。

Samplerate

String

采样率。默认值:44100,支持22050、32000、44100、48000、96000,单位:Hz。若视频容器格式为flv,音频编解码格式选择为mp3时,采样率不支持32000、48000、96000;音频编解码格式为mp3时,采样率不支持96000。

Bitrate

String

输出文件的音频码率。值范围:[8,1000],单位:Kbps,默认值:128 。

Channels

String

声道数。默认值:2。当Codec设置为mp3时,声道数只支持1、2;当Codec设置为aac时,声道数只支持1、2、4、5、6、8。

Remove

String

是否删除音频流。true表示删除,false表示保留,默认值:false。

以下表格显示音频转码编解码格式与容器格式的组合支持情况:

Container

Audio Codecs

mp3

MP3

mp4

AAC

ogg

VORBIS、FLAC

flac

FLAC

JSON对象TransConfig详情

参数

值类型

是否必选

描述

TransMode

String

转码模式。默认值:onepass,可选范围onepass、twopass、CBR。

AdjDarMethod

String

分辨率改写方式。默认值:none,可选范围rescale、crop、pad、none。

IsCheckReso

String

是否检查分辨率。如果输出分辨率大于输入分辨率(判断条件是宽或高),则输出分辨率等于输入分辨率。true表示检查,false表示不检查,默认值:false。

IsCheckResoFail

String

是否检查分辨率。如果输出分辨率大于输入分辨率(判断条件是宽或高),则返回转码失败。true表示检查,false表示不检查,默认值:false。

IsCheckVideoBitrate

String

是否检查视频码率。如果视频输出码率大于视频输入码率,则视频输出码率等于视频输入码率。true表示检查,false表示不检查,默认值:false。

IsCheckAudioBitrate

String

是否检查音频码率。如果音频输出码率大于音频输入码率,则音频输出码率等于音频输入码率。true表示检查,false表示不检查,默认值:false。

IsCheckAudioBitrateFail

String

当输出音频码率大于媒体源音频码率时,true表示不进行转码,false表示不检查,默认值:false,此值优先级大于IsCheckAudioBitrate。

IsCheckVideoBitrateFail

String

当输出视频码率大于媒体源视频码率时,true表示不进行转码,false表示不检查,默认值:false,此值优先级大于IsCheckVideoBitrate。

JSON对象MuxConfig详情

参数

值类型

是否必选

描述

Segment

String

JSON对象,切片配置字段。参见Segment详情。

Segment详情

参数

值类型

是否必选

描述

Duration

String

分片时长。整数值,单位:秒,范围:[1,60],默认值:10秒。

ForceSegTime

String

指定分片时间列表,逗号分隔,最多可指定10个分片时间点。小数型,支持3位小数,单位:秒。示例:23、55、60,代表在23,55,60秒处分片。

返回数据

名称 类型 示例值 描述
RequestId String FA258E67-09B8-4EAA-8F33-BA567834A2C3

请求ID。

Template Object

转码模板详细信息。

Video Object

视频编解码配置。

Bufsize String 6000

缓冲区大小。

  • 默认值:6000
  • 单位:Kb。
LongShortMode String false

是否开启横竖屏自适应(长短边模式)。默认值:false。取值:

  • true:开启横竖屏自适应。
  • false:关闭横竖屏自适应。
说明 转码输出的宽对应输入片源的长边(竖屏为片源的高),高对应输入视频的短边(竖屏为片源的宽)。
Degrain String 10

视频质量控制度 。

BitrateBnd Object

视频码率范围。

Max String 1500

最大码率。

Min String 800

最小码率。

PixFmt String yuv420p

视频颜色格式。范围yuv420p、yuvj420p等标准颜色格式。默认值:yuv420p原始颜色格式

Pad String 1280:800:0:140

视频贴黑边。参数格式:width:height:left:top。

Codec String H.264

编解码格式。支持H.264、H.265、GIF、WEBP。默认值:H.264

Height String 800

视频高度。

  • 单位:px。
  • 默认值:视频原始高度
Qscale String 1

独立去噪算法强度。

Crop String border

视频画面裁切。支持2种方式:

  • 自动检测黑边并裁切:设置为“border”。
  • 自定义裁切:自定义参数并裁剪。参数格式:width:height:left:top。示例:1280:800:0:140。
Bitrate String 500

视频输出文件的码率。单位:Kbps。

Maxrate String 500

视频码率峰值。单位Kbps。

MaxFps String 60

最大帧率。

Profile String high

编码级别。

  • baseline:适合移动设备。
  • main:适合标准分辨率设备。
  • high:适合高分辨率设备。
  • 默认值:high

最佳实践:如果您有多个清晰度,建议最低清晰度配成baseline,以保证最低端设备可播放。其他清晰度配置为main或high。

说明 目前仅H.264支持此参数。
Crf String 15

码率-质量控制因子。默认值:编码格式未H264,默认值为23。编码格式为H265,默认值为26

说明 如果设置了Crf,则Bitrate的设置失效。
Remove String false

是否删除视频流。

  • true:删除。
  • false:保留。
  • 默认值:false
Gop String 10s

关键帧间最大时间间隔或者最大帧数。最大时间间隔时,必传单位为秒。最大帧数时无单位。默认值:10s

Width String 256

宽。

  • 默认值:视频原始宽度
  • 单位:px。
Fps String 25

帧率。默认值:取输入文件帧率。当输入文件帧率超过60时取60。单位:fps。

Preset String fast

视频算法器预置。默认值:medium。可取值:

  • veryfast:超快
  • fast:快
  • medium:中等
  • slow:慢
  • slower:超慢
说明 目前仅H.264支持此参数。
ScanMode String interlaced

扫描模式。取值:

  • interlaced:交叉扫描。
  • progressive:逐行扫描。
ResoPriority String 0

分辨率调整优先级。

TransConfig Object

转码通用配置。

IsCheckAudioBitrate String true

是否检查音频码率。

如果音频输出码率大于音频输入码率,则音频输出码率等于音频输入码率。

  • true:表示检查。
  • false:表示不检查。
  • 默认值:false
TransMode String onepass

转码模式。可选范围:

  • onepass
  • twopass
  • CBR
  • 默认值:onepass
IsCheckReso String true

是否检查分辨率。

  • true表示检查。
  • false表示不检查。
  • 默认值:false
说明 如果输出分辨率大于输入分辨率(判断条件是宽或高),则输出分辨率等于输入分辨率。
IsCheckVideoBitrateFail String true

当输出视频码率大于媒体源视频码率时,此值优先级大于IsCheckVideoBitrate。

  • true表示不进行转码。
  • false表示不检查。
  • 默认值:false
AdjDarMethod String rescale

分辨率改写方式。默认值:none。可选范围:

  • rescale:范围拉伸。
  • crop:批量裁剪。
  • none:不改变。
IsCheckVideoBitrate String true

是否检查视频码率。

  • true表示检查。
  • false表示不检查。
  • 默认值:false
说明 如果视频输出码率大于视频输入码率,则视频输出码率等于视频输入码率。
IsCheckResoFail String true

是否检查分辨率。

  • true表示检查。
  • false表示不检查。
  • 默认值:false
说明 如果输出分辨率大于输入分辨率(判断条件是宽或高),则返回转码失败。
IsCheckAudioBitrateFail String true

当输出音频码率大于媒体源音频码率时,此值优先级大于IsCheckAudioBitrate

  • true表示不进行转码。
  • false表示不检查。
  • 默认值:false
State String Narmal

模板的状态。

  • Normal:正常。
  • Deleted:已删除。
MuxConfig Object

转码封包配置。

Webp Object

Webp对应的封包配置。

Loop String 0

循环次数。

Gif Object

Gif对应的封包配置。

FinalDelay String 0

终帧暂停时间。单位:厘秒。

DitherMode String sierra

调色板颜色抖动方式。可选值sierra、bayer。

Loop String 0

循环次数。

IsCustomPalette String false

自定义调色板功能。

Segment Object

切片配置。

Duration String 10

分片时长。单位:秒。

Name String mps-example

模板名称。

Audio Object

音频编解码配置。

Profile String aac_low

音频编码预置。当Codecaac时可以设置如下范围中的值:

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

是否删除音频流。

  • true:表示删除。
  • false:表示保留。
  • 默认值:false
Codec String aac

音频编解码格式。默认值:aac。可选值:

  • aac
  • mp3
  • vorbis
  • flac
Samplerate String 44100

采样率。

  • 单位:Hz。
  • 默认值:44100
Qscale String 5

独立去噪算法强度。

Channels String 2

声道数。默认值:2

Volume Object

音量详情。

Method String auto

音量调整方式。可取值:

  • auto:自动调整。
  • dynamic:动态调整。
  • linear:线性调整。
Level String -20

音量调整幅度。

  • 默认值:-20
  • 单位:db。
Bitrate String 500

输出文件的音频码率。

  • 单位:Kbps。
  • 默认值:128
Id String 16f01ad6175e4230ac42bb5182cd****

转码模板ID。建议您保存此ID便于后续调用其他相关接口时使用。

Container Object

容器。

Format String mp4

容器格式。

示例

请求示例

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"}}
&<公共请求参数>

正常返回示例

XML格式

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格式

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

错误码

访问错误中心查看更多错误码。