文档

AddTemplate - 新增自定义转码模版

更新时间:

创建自定义模板,包含容器信息,视频跟音频流等设置。

接口说明

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

QPS 限制

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

调试

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

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
mts:AddTemplatecreate
  • 全部资源
    *

请求参数

名称类型必填描述示例值
Namestring

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

mps-example
Containerstring

容器,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。
{"Format":"mp4"}
Videostring

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

说明 不设置 Video 参数则转码输出不包括视频流;如需保留视频流则必须设置此对象。
{"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"}
Audiostring

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

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

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

{"TransMode":"onepass"}
MuxConfigstring

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

{"Segment":{"Duration":"10"}}

JSON 对象 Container 详情

参数值类型是否必选描述
FormatString默认值: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 详情

参数值类型是否必选描述
CodecString编解码格式。支持 H.264、H.265、GIF、WEBP,默认值:H.264。
ProfileString编码级别。支持 baseline(适合移动设备)、main(适合标准分辨率设备)、high(适合高分辨率设备),默认值:high。最佳实践:如果您有多个清晰度,建议最低清晰度配成 baseline,以保证最低端设备可播放。其他清晰度配置为 main 或 high。目前仅 H.264 支持此参数。
BitrateString值范围:10~50000,单位:Kbps。
CrfString码率-质量控制因子。值范围:0~51,默认值:26。如果设置了 Crf,则 Bitrate 的设置失效。
WidthString宽。默认值:视频原始宽度,值范围:128~4096,单位:px。
HeightString高。默认值:视频原始高度,值范围:128~4096,单位:px。
FpsString帧率。默认值:取输入文件帧率。当输入文件帧率超过 60 时取 60。值范围:0~60。单位:fps。
GopString关键帧间最大时间间隔或者最大帧数。最大时间间隔时,必传单位 s。默认值:10s。最大帧数时,无单位,值范围:1~100000。
PresetString视频算法器预置。支持 veryfast(超快)、fast(快)、medium(中等)、slow(慢)、slower(超慢)。默认值:medium。目前仅 H.264 支持此参数。
ScanModeString扫描模式。支持 interlaced、progressive。
BufsizeString缓冲区大小。值范围:[1000,128000],默认值:6000,单位:Kb。
MaxrateString视频码率峰值。值范围[10,50000],单位 Kbps。
PixFmtString视频颜色格式。范围 yuv420p,yuvj420p 等标准颜色格式。默认值:yuv420p 或原始颜色格式。
RemoveString是否删除视频流。true 表示删除,false 表示保留,默认值:false。
CropString视频画面裁切。支持 2 种方式:自动检测黑边并裁切,设置为“border”。自定义裁切,参数格式:width:height:left:top。示例:1280:800:0:140。
PadString视频贴黑边。参数格式:width:height:left:top。示例:1280:800:0:140 。
LongShortModeString是否开启横竖屏自适应(即:长短边模式)。转码输出的宽对应输入片源的长边(竖屏为片源的高),高对应输入视频的短边(竖屏为片源的宽),true 表示开启,false 表示关闭,默认值:false。

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

ContainerAudio CodecsVideo Codecs
flvAAC、MP3H.264
mp4AAC、MP3H.264、H.265
tsAAC、MP3H.264、H.265
m3u8AAC、MP3H.264、H.265
gif不支持GIF

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

Video/CodecH.264H.265GIF
ProfileYNN
BitrateYYN
CrfYYN
WidthYYY
HeightYYY
FpsYYY
GopYYN
PresetYNN
ScanModeYYY
BufsizeYYN
MaxrateYYN
PixFmtYYbgr8

JSON 对象 Audio 详情

参数值类型是否必选描述
CodecString音频编解码格式,AAC、MP3、VORBIS、FLAC。默认值:AAC。
ProfileString音频编码预置。当 Codec 为 AAC 时,范围 aac_low、aac_he、aac_he_v2、aac_ld、aac_eld。
SamplerateString采样率。默认值:44100,支持 22050、32000、44100、48000、96000,单位:Hz。若视频容器格式为 flv,音频编解码格式选择为 mp3 时,采样率不支持 32000、48000、96000;音频编解码格式为 mp3 时,采样率不支持 96000。
BitrateString输出文件的音频码率。值范围:[8,1000],单位:Kbps,默认值:128 。
ChannelsString声道数。默认值:2。当 Codec 设置为 mp3 时,声道数只支持 1、2;当 Codec 设置为 aac 时,声道数只支持 1、2、4、5、6、8。
RemoveString是否删除音频流。true 表示删除,false 表示保留,默认值:false。

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

ContainerAudio Codecs
mp3MP3
mp4AAC
oggVORBIS、FLAC
flacFLAC

JSON 对象 TransConfig 详情

参数值类型是否必选描述
TransModeString转码模式。默认值:onepass,可选范围 onepass、twopass、CBR。
AdjDarMethodString分辨率改写方式。默认值:none,可选范围 rescale、crop、pad、none。
IsCheckResoString是否检查分辨率。如果输出分辨率大于输入分辨率(判断条件是宽或高),则输出分辨率等于输入分辨率。true 表示检查,false 表示不检查,默认值:false。
IsCheckResoFailString是否检查分辨率。如果输出分辨率大于输入分辨率(判断条件是宽或高),则返回转码失败。true 表示检查,false 表示不检查,默认值:false。
IsCheckVideoBitrateString是否检查视频码率。如果视频输出码率大于视频输入码率,则视频输出码率等于视频输入码率。true 表示检查,false 表示不检查,默认值:false。
IsCheckAudioBitrateString是否检查音频码率。如果音频输出码率大于音频输入码率,则音频输出码率等于音频输入码率。true 表示检查,false 表示不检查,默认值:false。
IsCheckAudioBitrateFailString当输出音频码率大于媒体源音频码率时,true 表示不进行转码,false 表示不检查,默认值:false,此值优先级大于 IsCheckAudioBitrate。
IsCheckVideoBitrateFailString当输出视频码率大于媒体源视频码率时,true 表示不进行转码,false 表示不检查,默认值:false,此值优先级大于 IsCheckVideoBitrate。

JSON 对象 MuxConfig 详情

参数值类型是否必选描述
SegmentStringJSON 对象,切片配置字段。参见 Segment 详情。

Segment 详情

参数值类型是否必选描述
DurationString分片时长。整数值,单位:秒,范围:[1,60],默认值:10 秒。
ForceSegTimeString指定分片时间列表,逗号分隔,最多可指定 10 个分片时间点。小数型,支持 3 位小数,单位:秒。示例:23、55、60,代表在 23,55,60 秒处分片。

返回参数

名称类型描述示例值
object

返回参数。

RequestIdstring

请求 ID。

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

转码模板详细信息。

Videoobject

视频编解码配置。

Bufsizestring

缓冲区大小。

  • 默认值:6000
  • 单位:Kb。
6000
LongShortModestring

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

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

视频质量控制度 。

10
BitrateBndobject

视频码率范围。

Maxstring

最大码率。

1500
Minstring

最小码率。

800
PixFmtstring

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

yuv420p
Padstring

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

1280:800:0:140
Codecstring

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

H.264
Heightstring

视频高度。

  • 单位:px。
  • 默认值:视频原始高度
800
Qscalestring

独立去噪算法强度。

1
Cropstring

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

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

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

500
Maxratestring

视频码率峰值。单位 Kbps。

500
MaxFpsstring

最大帧率。

60
Profilestring

编码级别。

  • baseline:适合移动设备。

  • main:适合标准分辨率设备。

  • high:适合高分辨率设备。

  • 默认值:high

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

说明 目前仅 H.264 支持此参数。
high
Crfstring

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

说明 如果设置了 Crf,则 Bitrate 的设置失效。
15
Removestring

是否删除视频流。

  • true:删除。

  • false:保留。

  • 默认值:false

false
Gopstring

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

10s
Widthstring

宽。

  • 默认值:视频原始宽度
  • 单位:px。
256
Fpsstring

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

25
Presetstring

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

  • veryfast:超快

  • fast:快

  • medium:中等

  • slow:慢

  • slower:超慢

说明 目前仅 H.264 支持此参数。
fast
ScanModestring

扫描模式。取值:

  • interlaced:交叉扫描。

  • progressive:逐行扫描。

interlaced
ResoPrioritystring

分辨率调整优先级。

0
Hdr2sdrstring

是否开启 hdr2sdr 功能。启用时会把 hdr 的视频转成 sdr。

true
NarrowBandobject

窄带高清设置参数

Versionstring

窄带高清版本,可选值:1.0 。

1.0
Abrmaxfloat

动态码率上限,设置后平均码率范围 (0, 1000000]。

3000
MaxAbrRatiofloat

码率上限最大倍率,设置后 abrmax 不会超过视频源码率的 x 倍。范围 (0, 1.0]

1.0
TransConfigobject

转码通用配置。

IsCheckAudioBitratestring

是否检查音频码率。当输出音频码率大于媒体源音频码率时,则视为输出音频码率等于媒体源音频码率,即设置的音频码率参数不会生效。此值优先级小于 IsCheckAudioBitrateFail。

  • true 表示检查。
  • false 表示不检查。
  • 默认值:
    • 参数为空,并且 codec 和输入源不一样:false。
    • 参数为空,并且 codec 和输入源一样:true。
true
TransModestring

转码模式。可选范围:

  • onepass

  • twopass

  • CBR

  • 默认值:onepass

onepass
IsCheckResostring

是否检查分辨率。如果输出分辨率大于输入分辨率(判断条件是宽或高),则输出分辨率等于输入分辨率。

  • true 表示检查。
  • false 表示不检查。
  • 默认值:false
true
IsCheckVideoBitrateFailstring

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

  • true 表示不进行转码。

  • false 表示不检查。

  • 默认值:false

true
AdjDarMethodstring

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

  • rescale:范围拉伸。

  • crop:批量裁剪。

  • none:不改变。

rescale
IsCheckVideoBitratestring

是否检查视频码率。如果视频输出码率大于视频输入码率,则视频输出码率等于视频输入码率。

  • true 表示检查。

  • false 表示不检查。

  • 默认值:false

true
IsCheckResoFailstring

是否检查分辨率。如果输出分辨率大于输入分辨率(判断条件是宽或高),则返回转码失败。

  • true 表示检查。

  • false 表示不检查。

  • 默认值:false

true
IsCheckAudioBitrateFailstring

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

  • true 表示不进行转码。

  • false 表示不检查。

  • 默认值:false

true
Statestring

模板的状态。

  • Normal:正常。

  • Deleted:已删除。

Normal
MuxConfigobject

转码封包配置。

Webpobject

Webp 对应的封包配置。

Loopstring

循环次数。

0
Gifobject

Gif 对应的封包配置。

FinalDelaystring

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

0
DitherModestring

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

sierra
Loopstring

循环次数。

0
IsCustomPalettestring

自定义调色板功能。

false
Segmentobject

切片配置。

Durationstring

分片时长。单位:秒。

10
Namestring

模板名称。

mps-example
Audioobject

音频编解码配置。

Profilestring

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

  • aac_low

  • aac_he

  • aac_he_v2

  • aac_ld

  • aac_eld

aac_low
Removestring

是否删除音频流。

  • true:表示删除。

  • false:表示保留。

  • 默认值:false

true
Codecstring

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

  • aac

  • mp3

  • vorbis

  • flac

aac
Sampleratestring

采样率。

  • 单位:Hz。
  • 默认值:44100
44100
Qscalestring

独立去噪算法强度。

5
Channelsstring

声道数。默认值:2

2
Volumeobject

音量详情。

Methodstring

音量调整方式。可取值:

  • auto:自动调整。

  • dynamic:动态调整。

  • linear:线性调整。

auto
Levelstring

音量调整幅度。

  • 默认值:-20

  • 单位:db。

-20
IntegratedLoudnessTargetstring

目标音量。

当指定 Method 为 dynamic 时生效。

单位:db。

值范围:[-70,-5]。

默认值:-6。

TruePeakstring

最大峰值。

当指定 Method 为 dynamic 时生效。

单位:db。

值范围:[-9,0]。

默认值:-1。

LoudnessRangeTargetstring

相对目标音量的波动范围。

当指定 Method 为 dynamic 时生效。

单位:db。

值范围:[1,20]。

默认值:8。

PeakLevelstring

音量调整系数。

当指定 Method 为 adaptive 时生效。

值范围:[0,1]。

默认值:0.9。

Bitratestring

输出文件的音频码率。

  • 单位:Kbps。
  • 默认值:128
500
Idstring

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

16f01ad6175e4230ac42bb5182cd****
Containerobject

容器。

Formatstring

容器格式。

mp4

示例

正常返回示例

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

错误码

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

变更历史

变更时间变更内容概要操作
2024-03-13OpenAPI 返回结构发生变更查看变更详情
2024-01-04OpenAPI 返回结构发生变更查看变更详情