使用AddTemplate介面新增自訂轉碼模板-ApsaraVideo for Media Processing-阿里雲

建立自訂模板，包含容器資訊，視頻跟音頻流等設定。

介面說明

本介面參數中包含容器資訊、視頻和音頻流等設定，如果相應部分不做設定，則使用模板轉出來的碼流中也不會包含相應的資訊。

QPS 限制

本介面的單使用者 QPS 限制為 100 次/秒。超過限制，API 呼叫會被限流，這可能會影響您的業務，請合理調用。更多資訊，請參見 QPS 限制。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

mts:AddTemplate

create

*全部資源

*

無

請求參數

名稱	類型	必填	描述	樣本值
Name	string	是	模板名稱。最大長度 128 位元組。	mps-example
Container	string	否	容器，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"}
Video	string	否	視頻流配置。JSON 對象，更多資訊請參見 Video 詳情。說明不設定 Video 參數則轉碼輸出不包括視頻流；如需保留視頻流則必須設定此對象。	{"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"}
Audio	string	否	音頻流配置。JSON 對象，詳情參見 Audio 詳情。說明不設定 Audio 參數則轉碼輸出不包括音頻流；如需保留音頻流則必須設定此對象。	{"Codec":"H.264","Samplerate":"44100","Bitrate":"500","Channels":"2"}
TransConfig	string	否	轉碼通用配置。JSON 對象，詳情參見 TransConfig 詳情。不設定 TransConfig 參數則轉碼配置全部為預設值，如預設值不能滿足您的轉碼需求則必須按需設定此對象。	{"TransMode":"onepass"}
MuxConfig	string	否	切片配置欄位。JSON 對象，詳情參見 MuxConfig 詳情。不設定 MuxConfig 參數則轉碼輸出不分區，如需分區則必須設定此對象。	{"Segment":{"Duration":"10"}}

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 秒處分區。

返回參數

名稱	類型	描述	樣本值
	object	返回參數。
RequestId	string	請求 ID。	FA258E67-09B8-4EAA-8F33-BA567834A2C3
Template	object	轉碼模板詳細資料。
Video	object	視頻編解碼配置。
Bufsize	string	緩衝區大小。預設值：6000。單位：Kb。	6000
LongShortMode	string	是否開啟橫豎屏自適應（長短邊模式）。預設值：false。取值： true：開啟橫豎屏自適應。 false：關閉橫豎屏自適應。說明轉碼輸出的寬對應輸入片源的長邊（豎屏為片源的高），高對應輸入視頻的短邊（豎屏為片源的寬）。	false
Degrain	string	視頻品質控制度。	10
BitrateBnd	object	視頻碼率範圍。
Max	string	最大碼率。	1500
Min	string	最小碼率。	800
PixFmt	string	視頻顏色格式。範圍 yuv420p、yuvj420p 等標準顏色格式。預設值：yuv420p 或原始顏色格式。	yuv420p
Pad	string	視頻貼黑邊。參數格式：width:height:left:top。	1280:800:0:140
Codec	string	編解碼格式。支援 H.264、H.265、GIF、WEBP。預設值：H.264。	H.264
Height	string	視頻高度。單位：px。預設值：視頻原始高度。	800
Qscale	string	獨立去噪演算法強度。	1
Crop	string	視頻畫面裁切。支援 2 種方式：自動檢測黑邊並裁切：設定為“border”。自訂裁切：自訂參數並裁剪。參數格式：width:height:left:top。樣本：1280:800:0:140。	border
Bitrate	string	視頻輸出檔案的碼率。單位：Kbps。	500
Maxrate	string	視頻碼率峰值。單位 Kbps。	500
MaxFps	string	最大幀率。	60
Profile	string	編碼層級。 baseline：適合行動裝置。 main：適合標準解析度裝置。 high：適合高解析度裝置。預設值：high。最佳實務：如果您有多個清晰度，建議最低清晰度配成 baseline，以保證最低端裝置可播放。其他清晰度配置為 main 或 high。說明目前僅 H.264 支援此參數。	high
Crf	string	碼率-品質控制因子。預設值：編碼格式未 H264，預設值為 23。編碼格式為 H265，預設值為 26。說明如果設定了 Crf，則 Bitrate 的設定失效。	15
Remove	string	是否刪除視頻流。 true：刪除。 false：保留。預設值：false。	false
Gop	string	主要畫面格間最大時間間隔或者最大幀數。最大時間間隔時，必傳單位為秒。最大幀數時無單位。預設值：10s。	10s
Width	string	寬。預設值：視頻原始寬度。單位：px。	256
Fps	string	幀率。預設值：取輸入檔案幀率。當輸入檔案幀率超過 60 時取 60。單位：fps。	25
Preset	string	視頻演算法器預置。預設值：medium。可取值： veryfast：超快 fast：快 medium：中等 slow：慢 slower：超慢說明目前僅 H.264 支援此參數。	fast
ScanMode	string	掃描模式。取值： interlaced：交叉掃描。 progressive：漸進式掃描。	interlaced
ResoPriority	string	解析度調整優先順序。	0
Hdr2sdr	string	是否開啟 hdr2sdr 功能。啟用時會把 hdr 的視頻轉成 sdr。	true
NarrowBand	object	窄帶高清設定參數
Version	string	窄帶高清版本，可選值：1.0 。	1.0
Abrmax	number	動態碼率上限，設定後平均碼率範圍 (0, 1000000]。	3000
MaxAbrRatio	number	碼率上限最大倍率，設定後 abrmax 不會超過視頻源碼率的 x 倍。範圍 (0, 1.0]	1.0
TransConfig	object	轉碼通用配置。
IsCheckAudioBitrate	string	是否檢查音頻碼率。當輸出音頻碼率大於媒體源音頻碼率時，則視為輸出音頻碼率等於媒體源音頻碼率，即設定的音頻碼率參數不會生效。此值優先順序小於 IsCheckAudioBitrateFail。 true 表示檢查。 false 表示不檢查。預設值：參數為空白，並且 codec 和輸入源不一樣：false。參數為空白，並且 codec 和輸入源一樣：true。	true
TransMode	string	轉碼模式。可選範圍： onepass twopass CBR 預設值：onepass	onepass
IsCheckReso	string	是否檢查解析度。如果輸出解析度大於輸入解析度（判斷條件是寬或高），則輸出解析度等於輸入解析度。 true 表示檢查。 false 表示不檢查。預設值：false。	true
IsCheckVideoBitrateFail	string	是否檢查視頻碼率。當輸出視頻碼率大於媒體源視頻碼率時，此值優先順序大於 IsCheckVideoBitrate。 true 表示不進行轉碼。 false 表示不檢查。預設值：false。	true
AdjDarMethod	string	解析度改寫方式。預設值：none。可選範圍： rescale：範圍展開。 crop：批量裁剪。 none：不改變。	rescale
IsCheckVideoBitrate	string	是否檢查視頻碼率。如果視頻輸出碼率大於視頻輸入碼率，則視頻輸出碼率等於視頻輸入碼率。 true 表示檢查。 false 表示不檢查。預設值：false。	true
IsCheckResoFail	string	是否檢查解析度。如果輸出解析度大於輸入解析度（判斷條件是寬或高），則返迴轉碼失敗。 true 表示檢查。 false 表示不檢查。預設值：false。	true
IsCheckAudioBitrateFail	string	是否檢查音頻碼率。當輸出音頻碼率大於媒體源音頻碼率時，此值優先順序大於 IsCheckAudioBitrate。 true 表示不進行轉碼。 false 表示不檢查。預設值：false。	true
State	string	模板的狀態。 Normal：正常。 Deleted：已刪除。	Normal
MuxConfig	object	轉碼封包配置。
Webp	object	Webp 對應的封包配置。
Loop	string	迴圈次數。	0
Gif	object	Gif 對應的封包配置。
FinalDelay	string	終幀暫停時間。單位：厘秒。	0
DitherMode	string	調色盤顏色抖動方式。可選值 sierra、bayer。	sierra
Loop	string	迴圈次數。	0
IsCustomPalette	string	自訂調色盤功能。	false
Segment	object	切片配置。
Duration	string	分區時間長度。單位：秒。	10
Name	string	模板名稱。	mps-example
Audio	object	音頻編解碼配置。
Profile	string	音頻編碼預置。當 Codec 為 aac 時可以設定如下範圍中的值： aac_low aac_he aac_he_v2 aac_ld aac_eld	aac_low
Remove	string	是否刪除音頻流。 true：表示刪除。 false：表示保留。預設值：false。	true
Codec	string	音頻編解碼格式。預設值：aac。可選值： aac mp3 vorbis flac	aac
Samplerate	string	採樣率。單位：Hz。預設值：44100。	44100
Qscale	string	獨立去噪演算法強度。	5
Channels	string	聲道數。預設值：2。	2
Volume	object	音量詳情。
Method	string	音量調整方式。可取值： auto：自動調整。 dynamic：動態調整。 linear：線性調整。	auto
Level	string	音量調整幅度。預設值：-20。單位：db。	-20
IntegratedLoudnessTarget	string	目標音量。當指定 Method 為 dynamic 時生效。單位：db。值範圍：[-70,-5]。預設值：-6。
TruePeak	string	最大峰值。當指定 Method 為 dynamic 時生效。單位：db。值範圍：[-9,0]。預設值：-1。
LoudnessRangeTarget	string	相對目標音量的波動範圍。當指定 Method 為 dynamic 時生效。單位：db。值範圍：[1,20]。預設值：8。
PeakLevel	string	音量調整係數。當指定 Method 為 adaptive 時生效。值範圍：[0,1]。預設值：0.9。
Bitrate	string	輸出檔案的音頻碼率。單位：Kbps。預設值：128。	500
Id	string	轉碼模板 ID。建議您儲存此 ID 便於後續調用其他相關介面時使用。	16f01ad6175e4230ac42bb5182cd****
Container	object	容器。
Format	string	容器格式。	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"
    }
  }
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。