All Products
Search
Document Center

ApsaraVideo Media Processing:UpdateTemplate

Last Updated:Mar 03, 2024

A custom transcoding template cannot be updated if it is being used by a job that has been submitted.

Operation description

The ID of the template. You can obtain the template ID from the response of the AddTemplate operation.

QPS limits

You can call this operation up to 100 times per second. 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.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
TemplateIdstringYes

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

16f01ad6175e4230ac42bb5182cd****
NamestringYes

The container format. The value is a JSON object. Default format: MP4.

  • Video formats: FLV, MP4, HLS (M3U8 + TS), and MPEG-DASH (MPD + fMP4)
  • Audio formats: MP3, MP4, OGG, FLAC, and M4A
  • Images formats: GIF and WebP

For more information, see the Container parameter of the "Parameter details" topic.

MPS-example
ContainerstringNo

The configurations of the video stream. The value is a JSON object. For more information, see the Video parameter of the "Parameter details" topic.

{"Format":"mp4"}
VideostringNo

The configurations of the audio stream. The value is a JSON object. For more information, see the Audio parameter of the "Parameter details" topic.

{"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10"}
AudiostringNo

The transmuxing configurations. The value is a JSON object. For more information, see the MuxConfig parameter of the "Parameter details" topic.

{"Codec":"aac","Samplerate":"44100","Bitrate":"500","Channels":"2"}
MuxConfigstringNo

The general transcoding configurations. The value is a JSON object. For more information, see the TransConfig parameter of the "Parameter details" topic.

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

The ID of the request.

{"TransMode":"onepass"}

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The type of the transcoding template.

5E4FB22E-B9EA-4E24-8FFC-B407EA71QW21
Templateobject

The type of the transcoding template.

Videoobject

Indicates whether the auto-rotate screen feature is enabled.

  • 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.
  • true: The auto-rotate screen feature is enabled.
  • false: The auto-rotate screen feature is disabled.
  • Default value: false.
LongShortModestring

The size of the buffer.

  • Unit: KB.
  • Default value: 6000.
false
Bufsizestring

The level of quality control on the video.

6000
Degrainstring

The average bitrate range of the video.

10
BitrateBndobject

The upper limit of the total bitrate. Unit: Kbit/s.

Maxstring

The lower limit of the total bitrate. Unit: Kbit/s.

500
Minstring

The pixel format. Valid values: standard pixel formats such as yuv420p and yuvj420p.

100
PixFmtstring

The black borders added to the video.

  • Format: width:height:left:top.
  • Example: 1280:800:0:140.
yuv420p
Padstring

The video codec. Default value: H.264.

1280:800:0:140
Codecstring

The height of the output video.

  • Unit: pixel.
  • Default value: the height of the input video.
H.264
Heightstring

The level of the independent denoising algorithm.

800
Qscalestring

The method used to crop the video.

  • border: automatically detects and removes borders.
  • Value in the width:height:left:top format: crops the video based on custom settings.**** Example: 1280:800:0:140.
1
Cropstring

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

border
Bitratestring

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

200
Maxratestring

The maximum frame rate.

500
MaxFpsstring

The encoding profile. Valid values:

  • baseline: applicable to mobile devices.
  • main: applicable to standard-definition devices.
  • high: applicable to high-definition devices.
  • Default value: high.
60
Profilestring

The bitrate quality control factor.

  • Default value if the Codec parameter is set to H.264: 23. Default value if the Codec parameter is set to H.265: 26.
  • If this parameter is returned, the setting of the Bitrate parameter is invalid.
high
Crfstring

Indicates whether the video stream is deleted. Valid values:

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

The maximum number of frames between two keyframes. Default value: 250.

false
Gopstring

The width of the video.

  • Unit: pixel.
  • Default value: the width of the input video.
10
Widthstring

The frame rate.

  • A value of 60 is returned if the frame rate of the input video exceeds 60.
  • Default value: the frame rate of the input video.
256
Fpsstring

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

  • veryfast
  • fast
  • medium
  • slow
  • slower
25
Presetstring

The scan mode. Valid values:

  • interlaced: An interlaced scan is performed.
  • progressive: A progressive scan is performed.
medium
ScanModestring

The policy of resolution adjustment.

interlaced
ResoPrioritystring

The general transcoding configurations.

1
TransConfigobject

Indicates whether the audio bitrate is checked. If the bitrate of the output audio is greater than the bitrate of the input audio, the bitrate of the input audio is retained after transcoding. In this case, the specified audio bitrate does not take effect. This parameter has a lower priority than the IsCheckAudioBitrateFail parameter. Valid values:

  • true: The audio bitrate is checked.

  • false: The audio bitrate is not checked.

  • Default value:

    • If the parameter is left empty and the codec of the output audio is different from that of the input audio, the default value is false.
    • If the parameter is left empty and the codec of the output audio is the same as that of the input audio, the default value is true.
IsCheckAudioBitratestring

The transcoding mode. Default value: onepass. Valid values:

  • onepass
  • twopass
  • CBR
false
TransModestring

Indicates whether the resolution is checked. If the output resolution is higher than the input resolution based on the width or height, the input resolution is retained after transcoding. Valid values:

  • true: The resolution is checked.
  • false: The resolution is not checked.
  • Default value: false.
onepass
IsCheckResostring

Indicates whether the video bitrate is checked. This parameter has a higher priority than the IsCheckVideoBitrate parameter. Valid values:

  • true: The video bitrate is checked
  • false: The video bitrate is not checked.
  • Default value: false.
false
IsCheckVideoBitrateFailstring

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.
false
AdjDarMethodstring

Indicates whether the video bitrate is checked. If this parameter is set to true 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. Valid values:

  • true: The video bitrate is checked.
  • false: The video bitrate is not checked.
  • Default value: false.
none
IsCheckVideoBitratestring

Indicates whether the resolution is checked. If this parameter is set to true 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. Valid values:

  • true: The resolution is checked.
  • false: The resolution is not checked.
  • Default value: false.
false
IsCheckResoFailstring

Indicates whether to the audio bitrate is checked. This parameter has a higher priority than the IsCheckAudioBitrate parameter. Valid values:

  • true: The audio bitrate is checked.
  • false: The audio bitrate is not checked.
  • Default value: false.
false
IsCheckAudioBitrateFailstring

The status of the template. Valid values:

  • Normal: The template is normal.
  • Deleted: The template is deleted.
false
Statestring

The transmuxing configurations.

Normal
MuxConfigobject

The transmuxing configurations for WebP.

Webpobject

The loop count.

Loopstring

The transmuxing configurations for GIF.

0
Gifobject

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

FinalDelaystring

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

false
DitherModestring

The loop count.

bayer
Loopstring

Indicates whether the custom palette is used.

0
IsCustomPalettestring

The segment configurations.

0
Segmentobject

The length of the segment. Unit: seconds.

Durationstring

The name of the template.

10
Namestring

The audio codec configurations.

MPS-example
Audioobject

The audio codec configurations.

Profilestring

Indicates whether the audio stream is deleted.

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

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

  • aac
  • mp3
  • vorbis
  • flac
false
Codecstring

The sampling rate.

  • Unit: Hz.
  • Default value: 44100.
aac
Sampleratestring

The level of the independent denoising algorithm.

44100
Qscalestring

The number of sound channels. Default value: 2.

1
Channelsstring

The audio bitrate of the output file.

  • Valid values: 8 to 1000.****
  • Unit: Kbit/s.
  • Default value: 128.
2
Bitratestring

The ID of the transcoding template.

500
Volumeobject

The volume control configurations.

Methodstring

The volume adjustment method. Valid values:

  • auto
  • dynamic
  • linear
auto
TruePeakstring

The peak volume.

  • This parameter takes effect only if the value of Method is dynamic.
  • Unit: decibel.
  • Valid values: [-9,0].
  • Default value: -1.
-1
IntegratedLoudnessTargetstring

The expected volume.

  • This parameter takes effect only if the value of Method is dynamic.
  • Unit: decibel.
  • Valid values: [-70,-5].
  • Default value: -6.
-6
Levelstring

The increased volume relative to the volume of the input audio.

  • This parameter takes effect only if the value of Method is linear.
  • Unit: decibel.
  • Valid values: less than or equal to 20.
  • Default value: -20.
-20
LoudnessRangeTargetstring

The range of the volume relative to the expected volume.

  • This parameter takes effect only if the value of Method is dynamic.
  • Unit: decibel.
  • 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.

Idstring

The container configurations.

16f01ad6175e4230ac42bb5182cd****
Containerobject

The container format.

Examples

Sample success responses

JSONformat

{
  "RequestId": "5E4FB22E-B9EA-4E24-8FFC-B407EA71QW21",
  "Template": {
    "Video": {
      "LongShortMode": "false",
      "Bufsize": "6000",
      "Degrain": "10",
      "BitrateBnd": {
        "Max": "500",
        "Min": "100"
      },
      "PixFmt": "yuv420p",
      "Pad": "1280:800:0:140",
      "Codec": "H.264",
      "Height": "800",
      "Qscale": "1",
      "Crop": "border",
      "Bitrate": "200",
      "Maxrate": "500",
      "MaxFps": "60",
      "Profile": "high",
      "Crf": "15",
      "Remove": "false",
      "Gop": "10",
      "Width": "256",
      "Fps": "25",
      "Preset": "medium",
      "ScanMode": "interlaced",
      "ResoPriority": "1",
      "Hdr2sdr": ""
    },
    "TransConfig": {
      "IsCheckAudioBitrate": "false",
      "TransMode": "onepass",
      "IsCheckReso": "false",
      "IsCheckVideoBitrateFail": "false",
      "AdjDarMethod": "none",
      "IsCheckVideoBitrate": "false",
      "IsCheckResoFail": "false",
      "IsCheckAudioBitrateFail": "false"
    },
    "State": "Normal",
    "MuxConfig": {
      "Webp": {
        "Loop": "0"
      },
      "Gif": {
        "FinalDelay": "false",
        "DitherMode": "bayer",
        "Loop": "0",
        "IsCustomPalette": "0"
      },
      "Segment": {
        "Duration": "10"
      }
    },
    "Name": "MPS-example",
    "Audio": {
      "Profile": "aac_low",
      "Remove": "false",
      "Codec": "aac",
      "Samplerate": "44100",
      "Qscale": "1",
      "Channels": "2",
      "Bitrate": "500",
      "Volume": {
        "Method": "auto",
        "TruePeak": "-1",
        "IntegratedLoudnessTarget": "-6",
        "Level": "-20",
        "LoudnessRangeTarget": "8",
        "PeakLevel": ""
      }
    },
    "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-10The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.
2024-01-04The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.
2023-07-13The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.