Parameter details

Parameter

Type

Required

Description

Bucket

String

Yes

The Object Storage Service (OSS) bucket that stores the input file.

For more information about OSS buckets, see Terms.

Location

String

Yes

Enter the data center (OSS Region) for the OSS Bucket.

• The OSS bucket must reside in the same region as MPS.

• The regions must follow the OSS Region definitions. For more information, see Basic Concepts.

Object

String

Yes

The OSS path of the input file. The OSS path is a full path that includes the name of the input file.

• For more information about the term object key, see Terms.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

• For example, Alibaba Cloud/mts HD+.mp4 is encoded as %E9%98%BF%E9%87%8C%E4%BA%91/mts%20HD%2B.mp4.

Referer

String

No

The configuration of hotlink protection. If you enable the hotlink protection feature for the OSS bucket to allow only specified referers in the whitelist to download files, you must specify this parameter. If you do not enable the hotlink protection feature for the OSS bucket, you do not need to specify this parameter. For more information, see Hotlink protection.

• To use workflow transcoding, you must set the Referer in the console. For more information, see Set hotlink protection.

• If you call an API operation to submit a transcoding job, you must specify this parameter in the request.

Parameter

Type

Required

Description

OutputObject

String

Yes

The OSS path of the output file. The OSS path is a full path that includes the name of the output file.

• For more information about the term object key, see Terms.

• Placeholders are supported. For more information, see the Placeholder replacement rules section of this topic.

• Rules for specifying the file name extension:

  • Workflow: You do not need to specify the file name extension. MPS automatically appends the file name extension to the value of the OutputObject parameter based on the container format of the transcoding template.

  • Transcoding job: You must specify the file name extension, and the file name extension must match the container format of the transcoding template. If the container format is M3U8, MPS automatically adds the file name extension .m3u8 to the playlist. A five-digit serial number is automatically added as a suffix to the playlist name to generate the name of a media segment file. The five-digit serial number starts from 00001 and connects to the playlist name with a hyphen (-). The file name extension of a media segment file is .ts. For example, if the file name of the playlist is filename.m3u8, the name of the first media segment file is filename-00001.ts.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

• For example, the path of the input file is a/b/example.flv, and you want to set the path of the output file to a/b/c/example+test.mp4. In this case, you can use placeholders to specify the path of the output file in the format of {ObjectPrefix}/c/{FileName}+test.mp4. After URL encoding, the path is displayed as %7BObjectPrefix%7D/c/%7BFileName%7D%2Btest.mp4.

TemplateId

String

Yes

The ID of the transcoding template.

• You can use custom transcoding templates and system preset templates. For more information, see Custom Transcoding Templates and Preset Template Details.

• Example: S00000002-200040.

Container

Object

No

The container format. For more information, see the Container section of this topic.

• If you specify this parameter, the corresponding parameter in the specified transcoding template is overwritten.

Video

Object

No

The parameter related to video transcoding. For more information, see the Video section of this topic.

• If you specify this parameter, the corresponding parameter in the specified transcoding template is overwritten.

Audio

Object

No

The parameter related to audio transcoding. For more information, see the Audio section of this topic.

• If you specify this parameter, the corresponding parameter in the specified transcoding template is overwritten.

TransConfig

Object

No

The parameter related to the transcoding process. For more information, see the TransConfig section of this topic.

• If you specify this parameter, the corresponding parameter in the specified transcoding template is overwritten.

• Example: {"TransMode":"onepass","AdjDarMethod":"none","IsCheckVideoBitrateFail":"true","IsCheckAudioBitrateFail":"true"}.

VideoStreamMap

String

No

The identifier of the video stream to be retained in the input file. Valid values:

• Not specified: A default video stream is selected.

• 0:v:{Serial number}: A specific video stream is selected. The serial number specifies the subscript of the video stream. The serial number starts from 0. For example, 0:v:1 specifies that the second video stream is selected for transcoding.

• 0:v: All video streams are selected.

AudioStreamMap

String

No

The identifier of the audio stream to be retained in the input file. Valid values:

• Not specified: A default audio stream is selected. In most cases, a Chinese, multi-sound channel, and high-quality audio stream is preferred.

• 0:a:{Serial number}: A specific audio stream is selected. The serial number specifies the subscript of the audio stream. The serial number starts from 0. For example, 0:a:1 specifies that the second audio stream is selected for transcoding.

• 0:a: All audio streams are selected. This value is applicable to a multi-language dubbing scenario.

Rotate

String

No

The rotation angle of the video in the clockwise direction.

• Valid values: 0, 90, 180, and 270.

• Default value: 0, which specifies that the video is not rotated.

WaterMarks

Object[]

No

The watermarks. Watermarks are images or text added to video images. If you specify this parameter, the corresponding parameter in the specified watermark template is overwritten. For more information, see the WaterMarks section of this topic.

• You can add up to four watermarks to a transcoding job.

• The following code shows an example of a single image watermark: ["WaterMarkTemplateId":"88c6ca184c0e47098a5b665e2a12****"},{"InputFile":{"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example-logo.png"},{"Timeline":{"Start":"0","Duration":"ToEND"}}].

• Example of a single text watermark: ["Type":"Text","TextWaterMark":{"Content":"5rWL6K+V5paH5a2X5rC05Y2w","FontName":"SimSun","FontSize":"16","Top":2,"Left":10}].

DeWatermark

Object

No

You can perform blur processing. For more information, see Blur processing details.

• Example: {"0": [{"l":10,"t":10,"w":10,"h":10},{"l":100,"t":0.1,"w":10,"h":10}],"128000": [],"250000": [{"l":0.2,"t":0.1,"w":0.01,"h":0.05}]}.

SubtitleConfig

Object

No

The configurations of the hard subtitle. This parameter lets you add external subtitle files to the video. For more information, see the SubtitleConfig section of this topic.

• You can add up to four subtitle files to a transcoding job.

• Example: {"ExtSubtitleList":[{"Input":{"Bucket":"example-bucket-****","Location":"oss-cn-hangzhou","Object":"example.srt"},"CharEnc":"UTF-8"}]}.

Clip

Object

No

The clip. For more information, see the Clip section of this topic.

• Example: {"TimeSpan":{"Seek":"00:01:59.999","End":"18000.30"},"ConfigToClipFirstPart":false}, which specifies that the clip starts at 1 minute, 59 seconds, and 999 milliseconds and ends at the point in time that is 5 minutes and 30 milliseconds before the end of the video. The clip is cropped from the video that is formed by merging multiple input files.

MergeList

Object[]

No

The merge list. You can merge multiple input files and clips in sequence to generate a new video. For more information, see the MergeList section of this topic.

• You can specify only one of the MergeList and MergeConfigUrl parameters. The MergeConfigUrl parameter has a higher priority than the MergeList parameter.

• You can add up to four MergeURL parameters to a transcoding job. To add more MergeURL parameters to a transcoding job, you must specify the MergeConfigUrl parameter.

• Example for specifying a single MergeURL parameter: [{"MergeURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_comm_01.mp4"}].

• Example for specifying two MergeURL parameters: [{"MergeURL":"http://exampleBucket****m.oss-cn-hangzhou.aliyuncs.com/tail_comm_01.mp4","Start":"1","Duration":"20"},{"MergeURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_comm_02.mp4","Start":"5.4","Duration":"10.2"}].

MergeConfigUrl

String

No

The OSS path of the configuration file for merging clips.

• You can specify only one of the MergeList and MergeConfigUrl parameters. The MergeConfigUrl parameter has a higher priority than the MergeList parameter.

• The file must be stored in an OSS bucket. Example: http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/mergeConfigfile.

• The file contains multiple MergeURL parameters. Specify the MergeURL parameters in the order in which you want to merge the corresponding clips. You can specify up to 50 MergeURL parameters. For more information about the format, see the MergeList section of this topic. Example of the configuration file content: {"MergeList":[{"MergeURL":"http://exampleBucket****m.oss-cn-hangzhou.aliyuncs.com/tail_comm_01.mp4","Start":"1","Duration":"20"},{"MergeURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_comm_02.mp4","Start":"5.4","Duration":"10.2"}]}.

OpeningList

Object[]

No

The opening parts. Opening is a special merging effect that lets you embed opening parts at the beginning of the input video. The opening parts are displayed in Picture-in-Picture (PiP) mode. For more information, see the OpeningList section of this topic.

• You can add up to two opening parts to a transcoding job. Specify the opening parts in the order in which you want to embed the opening parts in the output video.

• Example: [{"OpenUrl":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/opening_01.flv","Start":"1","Width":"1920","Height":"1080"},{"OpenUrl":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/opening_02.flv","Start":"1","Width":"-1","Height":"full"}].

TailSlateList

Object[]

No

The ending parts. Ending is a special merging effect that lets you add ending parts to the end of the input video. The ending parts are displayed in fade-in and fade-out mode. For more information, see the TailSlateList section of this topic.

• You can add up to two ending parts to a transcoding job. Specify the ending parts in the order in which you want to embed the ending parts in the output video.

• Example: [{"TailUrl":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_01.flv","Start":"1","BlendDuration":"2","Width":"1920","Height":"1080","IsMergeAudio":false,"BgColor":"White"}].

Amix

Object[]

No

The audio mixing configuration. This parameter is suitable for scenarios in which you want to merge multiple audio tracks in a video or add background music. For more information, see the Amix section of this topic.

• You can add up to four mixed audio files to a transcoding job.

• Example for mixing two audio streams of an input file: [{"AmixURL":"input","MixDurMode":"longest","Start":"1","Duration":"2"}].

• Example for adding an external file and mixing it with the input file: [{"AmixURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail.flv","Map":"0:a:1","MixDurMode":"longest","Start":"1","Duration":"2"}].

MuxConfig

Object

No

The packaging configurations. For more information, see the MuxConfig section of this topic.

• If you specify this parameter, the corresponding parameter in the specified transcoding template is overwritten.

• Example: {"Segment":{"Duration":"10","ForceSegTime":"1,2,4,6,10,14,18"}}, which specifies that the video is forcibly segmented at the 1st, 2nd, 4th, 6th, 10th, 14th, 18th, 20th, 30th, 40th, 50th... seconds.

M3U8NonStandardSupport

Object

No

The non-standard support for the M3U8 format. For more information, see the M3U8NonStandardSupport section of this topic.

• Example: {"TS":{"Md5Support":true,"SizeSupport":true}}, which specifies that the MD5 value and size of each TS file are included in the output M3U8 video.

Encryption

String

No

The encryption configuration. This parameter takes effect only if the Container parameter is set to m3u8. For more information, see Encryption parameter details.

• Example: {"Type":"hls-aes-128","Key":"ZW5jcnlwdGlvbmtleTEyMw","KeyType":"Base64","KeyUri":"aHR0cDovL2FsaXl1bi5jb20vZG9jdW1lbnQvaGxzMTI4LmtleQ=="}.

UserData

String

No

The custom data, which can be up to 1,024 bytes in size.

Priority

String

No

The priority of the transcoding job in the MPS queue.

• Valid values: [1,10]. A value of 1 specifies the lowest priority, whereas a value of 10 specifies the highest priority.

• Default value: 6.

• Best practice: MPS queues have concurrency limits. If you submit many jobs, the jobs may be queued. We recommend that you configure a higher priority for the job that requires high time performance or processes important content.

Metadata

Map

No

The metadata for the container format of the output video, specified as JSON key-value pairs. Example: {"key1":"value1","key2":"value2"}.

• key maximum length: 64.

• value maximum length: 512.

• You can add up to 4 metadata key-value pairs.

Parameter

Type

Required

Description

Format

String

No

The container format.

• For more information about the supported formats and compatible codecs, see Supported formats.

  • Supported video formats: 3GP, AVI, FLV, F4V, fMP4, MKV, MOV, MP4, TS, MXF, WebM, M3U8, HLS-fMP4, MPD, CMAF-HLS, and CMAF-DASH.

  • Supported audio formats: AAC, M4A, MP2, MP3, MP4, Ogg, FLAC, M3U8, HLS-fMP4, MPD, CMAF-HLS, and CMAF-DASH.

  • Animated images: GIF and WebP.

• Default format: MP4.

Parameter

Type

Required

Description

Remove

String

No

Specifies whether to delete the video stream. Valid values:

• true: deletes the video stream. If you set this parameter to true, all video-related parameters are invalid.

• false: The item is retained.

• Default value: false.

Codec

String

No

The video encoding format.

• Valid values: H.264, H.265, AV1, GIF, and WEBP. For more information about the supported formats and compatible container formats, see Supported formats.

• Default value: H.264.

Width

String

No

The width or long side of the output video. If the LongShortMode parameter is set to false or left empty, this parameter specifies the width of the output video. If the LongShortMode parameter is set to true, this parameter specifies the long side of the output video.

• Unit: pixel.

• Valid values: [128,4096]. The value must be an even number.

• Default value:

  • If neither the Width nor Height parameter is specified, the default value is the width or long side of the input video.

  • If only the Height parameter is specified, the default value is calculated based on the aspect ratio of the input video.

Height

String

No

The height or short side of the output video. If the LongShortMode parameter is set to false or left empty, this parameter specifies the height of the output video. If the LongShortMode parameter is set to true, this parameter specifies the short side of the output video.

• Unit: pixel.

• Valid values: [128,4096]. The value must be an even number.

• Default value:

  • If neither Width nor Height is set, the shorter dimension of the input video is used.

  • If only the Width parameter is specified, the default value is calculated based on the aspect ratio of the input video.

LongShortMode

String

No

Specifies whether to enable automatic rotation (adapting to the long and short edges). This setting takes effect only when `Width` or `Height` is specified.

• true: The feature is enabled.

• false: Shutdown.

• Default value: false.

• Best practice: If your input videos contain both landscape and portrait videos, enable the automatic rotation feature and configure proportional scaling based on the resolution parameters to prevent video stretching and distortion. For an example, see Configure automatic rotation.

Fps

String

No

The frame rate of the video stream.

• Unit: frames per second.

• Valid values: (0,60].

• Default value: the frame rate of the input file. If the frame rate of the input file exceeds 60, 60 is used.

• Common values: 24, 25, and 30.

MaxFps

String

No

The maximum frame rate.

Gop

String

No

Set the interval between adjacent I-frames in time or frame count.

• Format of maximum time interval between two consecutive I frames: {Time}s. Valid values: [1,100000].

• Format of maximum frame interval between two consecutive I frames: {Number of frames}. Valid values: [1,100000].

• Default value: 10s, which specifies that the time interval between two consecutive I frames is 10 seconds.

• Best practice: We recommend that you set the parameter to a time interval from two to seven seconds in a streaming media scenario to reduce the amount of time taken to start playback and the response time to seeking.

Bitrate

String

No

The average bitrate of the output video. If you use the CRB, ABR, or VBR bitrate control mode, you must specify the Bitrate parameter, and you must set the TransMode parameter to a valid value. For more information, see the Bitrate control mode section of this topic.

• Unit: Kbit/s.

• Valid values: -1 and [10,50000]. A value of -1 indicates that the original bitrate of the input video is used.

• Best practice:

  • CBR: Set the TransMode parameter to CBR and the Bitrate, Maxrate, and Bufsize parameters to the same value.

  • ABR: Set the TransMode parameter to onepass and specify the Bitrate parameter. You can also specify the Maxrate and Bufsize parameters to control the bitrate range.

  • VBR: Set the TransMode parameter to twopass and specify the Maxrate or BitrateBnd parameter and the Bufsize parameter.

BitrateBnd

String

No

The average bitrate range of the output video.

• This parameter takes effect only if the Codec parameter is set to H.264.

• Example: {"Max":"5000","Min":"1000"}.

Maxrate

String

No

The peak bitrate of the output video. For more information, see the Bitrate control mode section of this topic.

• Unit: Kbit/s.

• Valid values: [10,50000].

Bufsize

String

No

The buffer size for bitrate control. You can specify this parameter to control the bitrate fluctuation. For more information, see the Bitrate control mode section of this topic.

• Unit: Kbit.

• Valid values: [1000,128000].

• Default value: 6000.

Crf

String

No

The quality control factor. To use the CRF mode, you must specify the Crf parameter and set the TransMode parameter to fixCRF. For more information, see the Bitrate control mode section of this topic.

• Valid values: [20,51].

• If the Codec parameter is set to H.264, the default value is 23. If the Codec parameter is set to H.265, the default value is 26. If the Codec parameter is set to AV1, the default value is 32.

• Best practice:

  • A value of 0 specifies that the video is lossless. A value of 51 specifies that the image quality is the worst. We recommend that you set the value to a number in the range of 23 to 29. You can adjust the value based on the complexity of the video image. If you increase or decrease the value by six, the bitrate is reduced by half or doubled. Under the same definition, you can set the value for an animated cartoon to be higher than that for a shot video.

  • The CRF mode gives priority to the video quality, and the bitrate of output videos is unpredictable. You can specify the Maxrate and Bufsize parameters to control the bitrate range.

Qscale

String

No

The value of the factor for video quality control. This parameter takes effect if you use the VBR mode.

• This parameter takes effect only if the Codec parameter is set to H.264.

• Valid values: [0,51].

Profile

String

No

Specifies the encoding profile. For more information, see Terms.

• This parameter takes effect only if Codec is set to H.264.

• Valid values: baseline, main, and high.

• Default value: high.

• Best practice: If you want to generate output videos in multiple definitions from the same video, we recommend that you set this parameter to baseline for the lowest definition. This ensures that the output video can be played on the full range of devices. If you want to generate output videos in other definitions, set this parameter to main or high.

Preset

String

No

The preset mode of the H.264 encoder.

• This parameter takes effect only if the Codec parameter is set to H.264.

• Valid values: veryfast, fast, medium, slow, and slower.

• Default value: medium.

ScanMode

String

No

The scan mode. Valid values:

• If you leave this parameter empty, the scan mode of the input file is used.

• auto: Performs deinterlacing automatically.

• progressive: A sequential, line-by-line scan.

• interlaced: The scan is interlaced.

• Default value: None.

Best practice: The interlaced scan mode saves data traffic than the progressive scan mode but provides poor image quality. Therefore, the progressive scan mode is commonly used in mainstream video production.

• If you set the ScanMode parameter to progressive or interlaced but this scan mode does not match that of the input file, the file fails to be transcoded.

• We recommend setting Original Video Mode or Automatic Deinterlacing to improve compatibility.

PixFmt

String

No

The color format of the video.

• To use the original color format, set PixFmt to "".

• Valid values include yuv420p, yuvj420p, yuv422p, yuvj422p, yuv444p, yuvj444p, yuv444p, yuv444p161e, pc, bt470bg, and smpte170m. If the Codec parameter is set to GIF, bgr8 is supported.

Crop

String

No

The method that is used to crop videos. The borders can be automatically detected and removed. You can also manually crop the video.

• Specify this parameter if the resolution of the input video is greater than that of the output video. Do not specify the AdjDarMethod parameter if this parameter is specified.

• Automatic black bar border removal.

• To use a custom cropping method, set the parameter in the format of {width}:{height}:{left}:{top}.

  • width: the width of the output video after cropping.

  • height: the height of the output video after cropping.

  • left: the left margin between the output image and the original image.

  • top: the upper margin between the output image and the original image.

• Example of custom cropping: 1920:800:0:140.

Pad

String

No

The video is padded with black bars.

• Specify this parameter if the resolution of the input video is less than that of the output video. Do not specify the IsCheckReso, IsCheckResoFail, or AdjDarMethod parameter if this parameter is specified.

• Format: {width}:{height}:{left}:{top}.

  • width: the width of the output video after the black borders are added.

  • height: the height of the output video after the black borders are added.

  • left: The left margin of the source frame relative to the output frame.

  • top: The margin between the top of the output frame and the top of the original frame.

• Example: 1920:1080:0:140.

Parameter

Type

Required

Description

Remove

String

No

Specifies whether to delete the audio stream.

• true: deletes the audio stream. If you set this parameter to true, all audio-related parameters are invalid.

• false: The resource is retained.

• Default value: false.

Codec

String

No

The audio codec format.

• Valid values: AAC, AC3, EAC3, MP2, MP3, FLAC, OPUS, VORBIS, WMA-V1, WMA-V2, and pcm_s16le. For more information about the supported formats and compatible container formats, see Supported formats.

• Default value: AAC.

Profile

String

No

The audio encoding profile.

• This parameter takes effect only if the Codec parameter is set to AAC.

• Valid values: aac_low, aac_he, aac_he_v2, aac_ld, and aac_eld. For more information about the term encoding profile, see Terms.

• Default value: aac_low.

Bitrate

String

No

The audio bitrate of the output file.

• Unit: Kbit/s.

• Valid values: [8,1000].

• Default value: 128.

• Common values: 64, 128, and 256.

Samplerate

String

No

The sampling rate.

• Unit: Hz.

• Valid values: 22050, 32000, 44100, 48000, and 96000.

  Note

  The supported sampling rates vary based on the encoding format and container format. For more information, see Audio sample rates. For example, if Codec is set to MP3, you cannot set this parameter to 96000. If Codec is set to FLV, you can set this parameter only to 22050 or 44100.

• Default value: 44100.

Channels

String

No

The number of sound channels.

• Valid values: 0, 1, 2, 4, 5, 6, and 8.

  • If the Codec parameter is set to MP3 or OPUS, you can set this parameter to 0, 1, or 2.

  • If the Codec parameter is set to AAC or FLAC, you can set this parameter to 0, 1, 2, 4, 5, 6, or 8.

  • If the Codec parameter is set to VORBIS, you can set this parameter to 2.

  • If the Format parameter is set to MPD, you cannot set this parameter to 8.

• Default value: 2.

• If you want to keep the original number of sound channels, set this parameter to 0.

Volume

String

No

The volume configuration. For more information, see the Volume section of this topic.

• This parameter is supported only if only one output audio stream is configured. This parameter is not supported if more than one output audio streams are configured.

Parameter

Type

Required

Description

Type

String

No

The type of the watermark. Valid values:

• Text: a text watermark. If you set this parameter to Text, you must specify the TextWaterMark parameter.

• Image: an image watermark. If you set this parameter to Image, you must specify the parameters related to the image watermark.

• Default value: Image.

TextWaterMark

Object

No

The configuration of the text watermark. For more information, see the TextWaterMark section of this topic.

• If the Type parameter is set to Text, this parameter is required.

• Example: {"Content":"5rWL6K+V5paH5a2X5rC05Y2w","FontName":"SimSun","FontSize":"16","Top":2,"Left":10}.

InputFile

Object

No

The file to be used as the image watermark. You can use the Bucket, Location, and Object parameters to specify the location of the file.

• The following types of files are supported: PNG static images in the .png format, PNG animated images in the .apng format, MOV files in the .mov format, and GIF files in the .gif format.

• The file must be stored in an OSS bucket. For more information, see the Input section of this topic.

• In the ApsaraVideo Media Processing API, the Object requires URL Encoding (based on UTF-8) before use.

• Example: {"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example-logo.png"}.

WaterMarkTemplateId

String

No

The ID of the image watermark template. If you do not specify this parameter, the following default configurations are used for the parameters related to the image watermark:

• The image watermark position is TopRight.

• Dx and Dy: 0.

• Width: 0.12 times the width of the output video.

• Height: proportionally scaled based on the width of the image watermark.

• Image watermark display time: Entire duration.

ReferPos

String

No

The location of the image watermark.

• Valid values: TopRight, TopLeft, BottomRight, and BottomLeft.

Dx

String

No

The horizontal offset of the image watermark relative to the output video. If you specify this parameter, the corresponding parameter in the specified watermark template is overwritten. The following value types are supported:

• Integer: the pixel value of the horizontal offset.

  • Unit: pixel.

  • Valid values: [8,4096].

• Decimal: the ratio of the horizontal offset to the width of the output video.

  • Valid values: (0,1).

  • Four decimal places are supported, such as 0.9999. Excessive decimal places are discarded.

Dy

String

No

The vertical offset of the image watermark relative to the output video. The following value types are supported:

• Integer: the pixel value of the vertical offset.

  • Unit: pixel.

  • Valid values: [8,4096].

• Decimal: the ratio of the vertical offset to the height of the output video.

  • Valid values: (0,1).

  • Four decimal places are supported, such as 0.9999. Excessive decimal places are discarded.

Width

String

No

You can set the width of the image watermark in two ways:

• Integer: the pixel value of the watermark width.

  • Range: [8,4096].

  • Unit: pixel.

• A decimal value that represents the output video width as a percentage.

  • Range: (0,1).

  • Supports four decimal places, such as 0.9999. Excessive decimal places are automatically discarded.

Height

String

No

You can set the height of the image watermark in two ways:

• Integer: the pixel value of the watermark height.

  • Range: [8,4096].

  • Unit: pixel.

• A decimal value that specifies the height as a proportion of the output video's height.

  • Range: (0,1).

  • Supports four decimal places, such as 0.9999. Excessive decimal places are automatically discarded.

Timeline

String

No

The display time of the image watermark. For more information, see the Timeline section of this topic.

Parameter

Type

Required

Description

Content

String

Yes

The text to be displayed as the watermark. The text must be encoded in the Base64 format.

• For example, to add the text watermark "test text watermark", set Content to "5rWL6K+V5paH5a2X5rC05Y2w".

FontName

String

No

Font.

• For more information about the supported fonts, see Fonts.

• Default value: SimSun.

FontSize

Int

No

Font size.

• Valid values: (4,120).

• Default value: 16.

FontColor

String

No

Font color.

• For more information about the supported colors, see the name column of FontColor.

• Default value: black.

FontAlpha

Float

No

Text transparency.

• Valid values: (0,1].

• Default value: 1.0.

BorderWidth

Int

No

Outline width

• Unit: pixel.

• Valid values: [0,4096].

• Default value: 0.

BorderColor

String

No

Outline color.

• For more information about the supported colors, see the name column of BorderColor.

• Default value: Black.

Top

Int

No

Top margin of the text.

• Unit: pixel.

• Valid values: [0,4096].

• Default value: 0.

Left

Int

No

Left margin.

• Unit: pixel.

• Valid values: [0,4096].

• Default value: 0.

Parameter

Type

Required

Description

Start

String

No

The beginning of the time range in which the image watermark is displayed.

• Format: sssss[.SSS].

• The valid value range is [0.000, 86399.999]. The transcoding process fails if the start time exceeds the duration.

• Default value: 0.

• Example: 18000.30.

Duration

String

No

The time range in which the image watermark is displayed.

• If the parameter is set to ToEND, the watermark is continuously displayed until the video ends.

• Format: sssss[.SSS]. Unit: seconds.

• Default value: ToEND.

Parameter

Type

Required

Description

Type

String

No

The type of watermark.

• Image: an image watermark.

• Default value: Image.

ReferPos

String

No

The location of the image watermark.

• Valid values: TopRight, TopLeft, BottomRight, and BottomLeft.

• The following figure shows an example on how to use the ReferPos, Dx, and Dy parameters to specify the location of the image watermark.

Dx

String

No

The horizontal offset of the image watermark relative to the output video. The following value types are supported:

• Integer: the pixel value of the horizontal offset.

  • Unit: pixel.

  • Valid values: [8,4096].

• Decimal: the ratio of the horizontal offset to the width of the output video.

  • Valid values: (0,1).

  • Four decimal places are supported, such as 0.9999. Excessive decimal places are discarded.

Dy

String

No

The vertical offset of the image watermark relative to the output video. The following value types are supported:

• Integer: the pixel value of the vertical offset.

  • Unit: pixel.

  • Valid values: [8,4096].

• Decimal: the ratio of the vertical offset to the height of the output video.

  • Valid values: (0,1).

  • Four decimal places are supported, such as 0.9999. Excessive decimal places are discarded.

Width

String

No

The width of the image watermark. The following value types are supported:

• Integer: the pixel value of the watermark width.

  • Unit: pixel.

  • Range: [8,4096].

• Decimal type: A ratio of the width of the output video resolution.

  • Value range: (0,1).

  • Supports four decimal places, such as 0.9999. Excessive decimal places are automatically discarded.

Height

String

No

The height of the image watermark can be set in one of two ways:

• Integer: the pixel value of the watermark height.

  • Unit: pixel.

  • Range: [8,4096].

• Decimal value: A ratio relative to the height of the output video resolution.

  • Value range: (0,1).

  • Supports four decimal places, such as 0.9999. Excessive decimal places are automatically discarded.

Timeline

String

No

Dynamic watermark: For more information, see Timeline parameter details.

Parameter

Type

Required

Description

ExtSubtitleList

Object[]

No

The external subtitles. For more information, see the ExtSubtitle section of this topic.

• You can add up to four subtitle files to a transcoding job.

• Example: [{"Input":{"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example.srt"},"CharEnc":"UTF-8"}].

Parameter

Type

Required

Description

Input

String

Yes

The external subtitle file. You can use the Bucket, Location, and Object parameters to specify the location of the file.

• The SRT and ASS formats are supported. The color information in the subtitle file can be read.

• The file must be stored in an OSS bucket. For more information, see the Input section of this topic.

• Placeholders are supported. For more information, see the Placeholder replacement rules section of this topic.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

• For example, if the path of the input file is a/b/example.flv and the path of the subtitle file is a/b/example-cn.mp4, you can use placeholders to specify the object in the following format: {ObjectPrefix}{FileName}-cn.srt. After the path is URL-encoded, the object is {"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"%7bObjectPrefix%7d%7bFileName%7d-cn.srt"}.

CharEnc

String

No

The encoding format of the external subtitles.

• Valid values: UTF-8, GBK, BIG5, and auto.

• Default value: auto.

FontName

String

No

The font of the subtitle.

• For more information about the supported fonts, see Fonts.

• Default value: SimSun.

FontSize

Int

No

The font size of the subtitle.

• Valid values: (4,120).

• Default value: 16.

Parameter

Type

Required

Description

TimeSpan

String

No

The time span of cropping a clip from the input file. For more information, see the TimeSpan section of this topic.

• Example for specifying the time span using the Duration parameter: {"Seek":"00:01:59.999","Duration":"180.30"}, which specifies that the clip starts at 1 minute, 59 seconds, and 999 milliseconds and ends at 5 minutes and 30 milliseconds.

• Example for specifying the time span using the End parameter: {"Seek":"00:01:59.999","End":"180.30"}, which specifies that the clip starts at 1 minute, 59 seconds, and 999 milliseconds and ends at the point in time that is 5 minutes and 30 milliseconds before the end of the video.

ConfigToClipFirstPart

Boolean

No

Specifies whether to perform video editing on the first segment.

• true: crops the first part of the file into a clip before clip merging.

• false: The content is first concatenated (transcoded) and then edited.

• Default value: false.

Parameter

Type

Required

Description

Seek

String

No

The start point in time of the clip. You can use this parameter to specify the start point in time of the clip. The default start point in time is the beginning of the video.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 00:01:59.999 or 180.30.

Duration

String

No

The length of the clip. You can specify the length of the clip relative to the point in time specified by the Seek parameter. By default, the length of the clip is from the point in time specified by the Seek parameter to the end of the video. You can specify only one of the Duration and End parameters. If you specify the End parameter, the setting of the Duration parameter is invalid.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 00:01:59.99 or 180.30.

End

String

No

The length of the ending part of the original video to be cropped out. You can specify only one of the Duration and End parameters. If you specify the End parameter, the setting of the Duration parameter is invalid.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 00:01:59.999 or 180.30.

Parameter

Type

Required

Description

MergeURL

String

Yes

The OSS path of the clip to be merged.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

• Example: http://exampleBucket****m.oss-cn-hangzhou.aliyuncs.com/tail_comm_01.mp4.

Start

String

No

The point in time at which the output clip is cut from the original clip. Specify this parameter if you want to merge only part of the video into the output file. The default start point in time is the beginning of the video.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 01:59:59.999 or 32000.23.

Duration

String

No

The length of the mixed video. The length is relative to the start point in time specified by the Start parameter. Specify this parameter if you want to merge only part of the video into the output file. By default, the length is the period from the start point in time specified by the Start parameter to the end of the video.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 01:59:59.999 or 32000.23.

Parameter

Type

Required

Description

OpenUrl

String

Yes

The OSS path of the opening part.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

• Example: http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/opening_01.flv.

Start

String

No

The duration that elapses after the input video is played before the opening scene is played. The value starts from 0.

• Unit: seconds.

• Default value: 0.

Width

String

No

The width of the output video can be set in three ways:

• Width: The width in pixels. The value must be an integer from 0 to 4096.

• -1: The width is equal to the width of the opening slate of the input video.

• Full: The video fills the entire playback area.

• Default value: -1.

Height

String

No

You can set the height of the output video in three ways:

• Width: The width in pixels. The value must be an integer from 0 to 4096.

• -1: Same as the height of the input video.

• full: Fills the entire video frame.

• Default value: -1.

Parameter

Type

Required

Description

TailUrl

String

Yes

The URL of the end slate video in OSS.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

• Example: http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_01.flv.

BlendDuration

String

No

The amount of time between the end of the main part and the beginning of the ending part. During the transition, the last frame of the main part fades out, and the first frame of the ending part fades in.

• Unit: seconds.

• Default value: 0.

Width

String

No

The width of the output ending part. Valid values:

• Width: The width, in pixels, must be in the range [0, 4096].

• -1: The width is the same as that of the input outro video.

• full: The video fills the entire frame.

• Default value: -1.

Height

String

No

The height of the output end slate has three available settings:

• Width: The width in pixels. The value must be an integer from 0 to 4096.

• -1: The height of the input slate video.

• full: The video fills the playback area.

• Default value: -1.

IsMergeAudio

Boolean

No

Specifies whether to append the audio of the outro video.

• true: Enables concatenation.

• false: No concatenation occurs.

• Default value: true.

BgColor

String

No

The color of the margin if the width and height of the ending part are less than those of the main part.

• For more information about the supported colors, see the name column of bgcolor.

• Default value: White.

Parameter

Type

Required

Description

AmixURL

String

Yes

The audio stream to be mixed supports two modes:

• input: mixes multiple audio streams of the input file. You can mix two audio streams of the input file.

• OSS path: adds an external audio stream. For example, you can add background music. You can mix an audio stream of the input file with the audio stream that is specified by the OSS path. Example: http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail.flv.

Map

String

No

To select the target audio stream for mixing in AmixURL, use the AudioStreamMap parameter to specify the ordinal number of the audio stream in the input file.

• Format: 0:a:{Serial number}. The serial number specifies the subscript of the audio stream. The serial number starts from 0.

• For example, 0:a:1 specifies the second audio stream.

MixDurMode

String

No

The duration of the mixed output file.

• first: The length of the input file is used.

• longest: The longer one in the lengths of the input file and the audio stream specified by the AmixURL parameter is used.

• Default value: longest.

Start

String

No

The start point in time of the audio stream. Specify this parameter if you want to mix only part of the audio into the output file. The default start point in time is the beginning of the audio.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 00:01:59.999 or 18000.30.

Duration

String

No

The length of the mixed audio. The length is relative to the start point in time specified by the Start parameter. Specify this parameter if you want to mix only part of the audio into the output file. By default, the length is the period from the start point in time specified by the Start parameter to the end of the audio.

• Format: hh:mm:ss[.SSS] or sssss[.SSS].

• Valid values: [00:00:00.000,23:59:59.999] or [0.000,86399.999].

• Example: 00:01:59.999 or 18000.30.

Parameter

Type

Required

Description

Segment

String

No

The segment configuration. For more information, see the Segment section of this topic.

• This parameter takes effect only if the container format is set to M3U8, HLS-FMP4, MPD, or CMAF.

• Example: {"Duration":"10","ForceSegTime":"1,2,4,6,10,14,18"}, which specifies that the video is forcibly segmented at the 1st, 2nd, 4th, 6th, 10th, 14th, 18th, 20th, 30th, 40th, 50th... seconds.

Parameter

Type

Required

Description

Duration

Int

No

The segment duration.

• Unit: seconds.

• Valid values: [1,60].

• Default value: 10, which specifies that the video is forcibly segmented at the 10th, 20th, 30th, and 40th seconds.

ForceSegTime

String

No

The points in time at which the video is forcibly segmented. Separate points in time with commas (,). You can specify up to 10 points in time.

• Format: {Point in time},{Point in time},{Point in time}.

• Type: decimal. This parameter supports up to three decimal places.

• Unit: seconds.

• Example: 1,2,4,6,10,14,18, which specifies that the video is forcibly segmented at the 1st, 2nd, 4th, 6th, 10th, 14th, and 18th seconds.

Parameter

Type

Required

Description

TS

Object

No

The non-standard support for TS files. For more information, see the TS section of this topic.

Parameter

Type

Required

Description

Md5Support

Boolean

No

Specifies whether to include the MD5 value of each TS file in the output M3U8 video.

SizeSupport

Boolean

No

Specifies whether to include the size of each TS file in the output M3U8 video.

Parameter

Type

Required

Description

Type

String

Yes

The encryption method of the video. Valid values:

• hls-aes-128: standard encryption.

KeyType

String

Yes

Key encryption method.

• Base64: basic encryption method.

• KMS: Key Management Service (KMS). KMS is used to generate plaintext and ciphertext keys.

Key

String

Yes

The ciphertext key for the encrypted video. The key format is determined by the encryption method.

• Base64:

  • Encrypt the plaintext key using Base64 and set this parameter to the ciphertext key that is generated.

  • The plaintext key is customized and can be up to 16 characters in length.

  • For example, the corresponding cyphertext key of the plaintext key "encryptionkey128" is "ZW5jcnlwdGlvbmtleTEyOA==".

• KMS:

  • Call the GenerateKMSDataKey operation, pass in the customer master key (CMK), and then set the KeySpec parameter to AES_128 to obtain the corresponding ciphertext key from the CiphertextBlob parameter.

KeyUri

String

Yes

This is the decryption service endpoint. You must set up the service yourself.

• The URL cannot be passed to MPS in plaintext. You must encrypt the URL in Base64.

• For example, if the URL is http://aliyun.com/document/hls128.key, the URL is encrypted into aHR0cDovL2FsaXl1bi5jb20vZG9jdW1lbnQvaGxzMTI4LmtleQ== in Base64.

SkipCnt

String

No

The number of clips that are not encrypted at the beginning of the video. This ensures a shorter loading time during startup.

• Example: 3.

Parameter

Type

Required

Description

Num

String

No

The number of snapshots to be captured.

• If you specify one of the Interval and Num parameters, the asynchronous mode is used by default. The value of the Num parameter must be greater than 0.

• If you leave the Num and Interval parameters empty and specify the Time parameter, the system synchronously captures one snapshot at the time that you specified.

• If you set the Num parameter to 1 and specify the Time parameter, the system asynchronously captures one snapshot at the time that you specified.

• If you set the Num parameter to a value greater than 1, the system starts to asynchronously capture snapshots at the time that you specified for the Time parameter and stops when the number of captured snapshots reaches the number you specified for the Num parameter. The snapshots are captured at the interval specified by the Interval parameter. If you do not specify the Interval parameter, the snapshots are captured every 10 seconds. If the result of Time + Interval × Num is greater than the length of the input video, only snapshots that are captured at the points in time within the length of the input video can be generated. After the snapshots are generated, the actual number of snapshots is returned.

• If you set the Num parameter to a value greater than 1 and the Interval parameter to 0, the system starts to asynchronously capture snapshots at the point in time that you specified for the Time parameter. The number of snapshots is determined by the Num parameter and the snapshots are evenly captured within the length of the input video.

Time

String

No

The point in time at which the system starts to capture snapshots in the input video.

• Unit: millisecond.

• If the value of the Time parameter exceeds the video length, the snapshots fail to be generated.

• This parameter is not required if snapshots are captured at specific points in time. In other scenarios, this parameter is required.

  Note

  In the scenario in which snapshots are captured at specific points in time, MPS converts the minimum point in time in the TimeArray parameter into a value in milliseconds. This value is used for the Time parameter in this scenario. If you specify the {SnapshotTime} placeholder in the output path, the placeholder is replaced with the value of the Time parameter.

Interval

String

No

The interval at which snapshots are captured.

• If you specify this parameter, the asynchronous mode is automatically used to capture snapshots.

• Set the Interval parameter to a value greater than 0 if you want to asynchronously capture multiple snapshots. Unit: seconds.

• The interval for asynchronous average screenshots is 0.

• The default value is 10. This value is submitted if `Num` is set but this parameter is not.

TimeArray

Array

No

The array of specific points in time. This parameter is required if you capture snapshots at specific points in time.

• The value must be a unique integer in milliseconds.

• The points in time cannot exceed the video length. Otherwise, snapshots cannot be captured.

• You can specify points in time in sequence or out of sequence. We recommend that you specify points in time in sequence. If you specify points in time out of sequence, MPS sorts these points in time.

FrameType

String

No

Specifies the type of screenshot.

• Default value: intra.

• normal: regular frames. The image quality of regular frames is lower than that of keyframes. In addition, it takes more time to capture regular frames than to capture keyframes. However, a regular frame can be captured at a specific point in time.

• intra (default): keyframes. Keyframes of videos have good image quality and can be captured quickly because keyframes are independently decoded. However, keyframes appear in a video at intervals and cannot be captured at specific points in time. If the point in time that you specify is not accurate, the system captures the keyframe that is nearest to the point in time that you specify. In this case, if the distance between two keyframes is greater than the interval at which snapshots are captured, the number of generated snapshots may be less than the number of snapshots that you want to capture.

Width

String

No

The width of snapshots.

• Unit: pixel.

• Valid values: [8,4096]. We recommend that you specify an even number.

• Default value:

  • By default, if you do not specify a width or height, the width of the input video is used.

  • If only the height is specified, the width of snapshots is calculated based on the aspect ratio of the input video.

Height

String

No

The height of snapshots.

• Unit: pixel.

• Valid values: [8,4096]. We recommend that you specify an even number.

• Default value:

  • By default, if you do not specify a width or height, the height of the input video is used.

  • If only the width is specified, the height of snapshots is calculated based on the aspect ratio of the input video.

BlackLevel

String

No

The upper limit of black pixels in a snapshot. If the black pixels in a snapshot exceed this value, the system determines that the image is a black screen. For more information about black pixels, see the description of the PixelBlackThreshold parameter.

PixelBlackThreshold

String

No

The color value threshold for pixels. If the color value of a pixel is less than the threshold, the system determines that the pixel is a black pixel.

• Valid values: [0,255]. 0 specifies a pure black pixel and 255 specifies a pure white pixel.

• If you want to improve the filtering of black screens, specify a higher value for this parameter. We recommend that you set this parameter to 30 and adjust the value as needed.

• For example, if you set this parameter to 100, the pixels whose color values are lower than 100 are considered black pixels.

Format

String

No

The format of the output file.

• If you set this parameter to vtt, the output file is in the WebVTT format. You must specify the SubOut parameter to determine whether to generate WebVTT files.

• By default, this parameter is left empty. In this case, the output file is generated in the JPG format.

SubOut

Object

No

The configurations of the WebVTT file. For more information, see the SubOut Webvtt section of this topic.

• The parameter is required if the Format parameter is set to vtt.

TileOut

Object

No

The image sprite configurations. For more information, see the TileOut section of this topic.

• After you set this parameter, the generated snapshots are combined into an image sprite. The TileOutputFile parameter specifies the output image sprite.

• If you leave this parameter empty, no image sprites are generated.

OutputFile

Object

Yes

The output is a single small image file stored at the location specified by the OSS Bucket, Location, and Object. For more information, see OutputFile screenshot details.

• The snapshot files are in the JPG format.

• Example: {"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example.jpg"}.

TileOutputFile

Object

No

The output image sprite. You must specify the storage path of the object in OSS. The value of this parameter is similar to that of the OutputFile parameter.

• This parameter is required if you specify the TileOut parameter to generate an image sprite.

• The puzzle file is in JPG format.

• Example: {"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example.jpg"}.

Parameter

Type

Required

Description

IsSptFrag

String

No

Specifies whether to generate WebVTT index files. Valid values:

• true: generates WebVTT index files. The WebVTT index files are stored in the same path as the snapshots.

• false: does not generate WebVTT index files. Only snapshots are exported.

• Default value: false.

Parameter

Type

Required

Description

Lines

Int

No

The number of rows that the tiled snapshot contains.

• Valid values: (0,10000].

• Default value: 10.

Columns

Int

No

The number of columns that the tiled snapshot contains.

• Valid values: (0,10000].

• Default value: 10.

CellWidth

String

No

Width of a single image.

• Unit: pixel.

• Default value: the width of the original snapshot.

CellHeight

String

No

Height of a single image.

• Unit: pixel.

• Default value: the height of the original snapshot.

Padding

String

No

Single-image pitch

• Unit: pixel.

• Default value: 0.

Margin

String

No

Frame width.

• Default value: 0.

• Unit: pixel.

Color

String

No

The background color. The background color that is used to fill the margins, the padding between snapshots, and the area in which no snapshots are displayed.

• You can specify a color keyword or random value for this parameter. For example, if you want to set the background color to black, you can specify the color keyword in one of the following formats: Black, black, and #000000.

• Default value: black.

IsKeepCellPic

String

No

Determines whether to retain individual thumbnails.

• true: The single graph is stored in OutputFile.

• false: The item is not retained.

• Default: false (not retained).

Parameter

Type

Required

Description

Bucket

String

Yes

The OSS bucket that stores the output files of individual small images.

• The bucket must comply with the OSS Bucket definitions. For more information, see Basic Concepts.

Location

String

Yes

The region in which the OSS bucket resides.

• The OSS bucket must reside in the same region as MPS.

• Adhere to the OSS Region definitions. For more information, see Basic Concepts.

Object

String

Yes

The path in which the output snapshots are stored in OSS.

• The path includes the file name and file name extension. For more information about the term object key, see Terms.

• Placeholders are supported. For more information, see the Placeholder replacement rules section of this topic.

• The only supported file name extension is .jpg.

• The path of an OSS object must be URL-encoded in UTF-8 before you use the path in MPS. For more information, see URL encoding.

Parameter

Type

Required

Description

QueueName

String

No

The MNS queue to attach. When a job in the MPS queue is complete, its execution result is sent to this queue. For more information about how to receive message notifications, see Receive message notifications.

• You can specify one of the QueueName and Topic parameters.

• Valid values: The MNS topics that you have created. If no active topics are available, you can go to Simple Message Queue (formerly MNS) to create one.

Topic

String

No

The SMQ topic in which you want to receive notifications. After the job is complete, the job results are pushed to the SMQ topic. Then, the SMQ topic pushes the message to multiple queues or URLs that subscribe to the topic. For more information about receiving notifications, see Receive notifications.

• You can specify one of the QueueName and Topic parameters.

• The value must be an MNS topic that you have created. If no topics are available, go to the Simple Message Queue (formerly MNS) console to create one.

Parameter

Type

Required

Description

Bucket

String

Yes

The OSS bucket that stores the input file.

• Grant read permission on the OSS bucket to ApsaraVideo Media Processing on the Bucket Authorization page in the OSS console.

• The bucket must conform to the OSS bucket definition. For more information, see Glossary.

Location

String

Yes

The region in which the OSS bucket resides.

Follow the OSS Location definition. For more information, see the Glossary.

Object

String

Yes

The OSS object that is used as the input file.

• The path of an OSS object must comply with RFC 2396 and be URL-encoded in UTF-8. For more information, see URL encoding.

• This complies with the OSS Object definition. For more information, see the Glossary.

Audio

String

No

The audio configuration of the input file. The value must be a JSON object.

• For more information, see the InputAudio section of this topic.

• Example: {"Channels":"2","Samplerate":"44100"}.

Container

String

No

The container configuration of the input file. The value must be a JSON object.

• For more information, see the InputContainer section of this topic.

• Example: {"Format":"u8"}.

Parameter

Type

Required

Description

Format

String

Yes

The audio format of the input file.

Valid values: alaw, f32be, f32le, f64be, f64le, mulaw, s16be, s16le, s24be, s24le, s32be, s32le, s8, u16be, u16le, u24be, u24le, u32be, u32le, and u8.

Parameter

Type

Required

Description

Channels

String

Yes

The number of sound channels in the input file. Valid values: [1,8].

Samplerate

String

Yes

The audio sampling rate of the input file.

• Valid values: (0,320000].

• Unit: Hz.

Parameter

Type

Required

Description

QualityControl

String

No

The configuration of the output file quality. The value must be a JSON object. For more information, see the QualityControl section of this topic.

PropertiesControl

String

No

The property configuration. The value must be a JSON object. For more information, see the PropertiesControl section of this topic.

Parameter

Type

Required

Description

RateQuality

String

No

The quality level of the output file.

• Valid values: (0,51).

• The value must be an integer.

• Default value: 25.

MethodStreaming

String

No

The playback mode. Valid values: network and local.

Default value: network.

Parameter

Type

Required

Description

Deinterlace

String

No

Determining the forced scan mode.

• Auto is short for Automatic.

• Force: forcibly runs deinterlacing.

• None: forbids deinterlacing.

Crop

String

No

The cropping configuration of the video image.

• The default value is Automatic.

• If you do not set this parameter to an empty JSON object, the Mode parameter is required.

• For more information, see the Crop section of this topic.

Parameter

Type

Required

Description

Mode

String

No

This parameter is required if the value of the Crop parameter is not an empty JSON object. Valid values:

• Auto (Automatic)

• Force: forcibly runs cropping.

• None: No operation is performed.

Width

Integer

No

Cropped width

• Valid values: [8,4096].

• If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.

Height

Integer

No

The height of the cropped image.

• Valid values: [8,4096].

• If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.

Top

Integer

No

The top margin to be cropped out.

• Valid values: [8,4096].

• If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.

Left

Integer

No

The left margin to be cropped out.

• Valid values: [8,4096].

• If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.

Parameter

Type

Required

Description

MergeList

String

No

Configuration field for video concatenation.

• The value must be a JSON array that contains up to four MergeURL parameters. For more information, see the MergeList section of this topic.

• Example: [{"MergeURL":"http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/k/mp4.mp4"},{"MergeURL":"http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/c/ts.ts","Start":"1:14","Duration":"29"}].

Parameter

Type

Required

Description

URL

String

No

The URL of the input file in OSS.

• Example: http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/example.flv.

• If you do not specify this parameter, the Bucket, Location, and Object parameters are required.

Bucket

String

No

• This value is required if you do not specify a URL.

• Otherwise, the setting of this parameter is invalid. Before you specify an OSS bucket, grant the write permissions on the OSS bucket to MPS on the Access Control page in the OSS console.

• For more information about the term bucket, see Glossary.

Location

String

No

• This value is required if you do not specify a URL.

• Otherwise, the value is invalid and the data center (OSS Location) of the OSS Bucket is output.

• This complies with the OSS Location definition. For more information, see the Glossary.

Object

String

No

• This value is required if you do not specify a URL.

• If the value is invalid, the output file (OSS Object) is encoded in UTF-8 and then URL-encoded as specified in RFC 2396. For more information, see URL Encoding.

• This must conform to the OSS Object definition. For more information, see the Glossary.

Parameter

Type

Required

Description

URI

String

No

The name of the output video stream, which must end with .m3u8. Example: a/b/test.m3u8. Format: ^[a-z]{1}[a-z0-9./-]+$.

RefActivityName

String

Yes

The name of the associated activity.

ExtXStreamInfo

Json

Yes

The information about the stream. Example: {"BandWidth": "111110","Audio": "auds","Subtitles": "subs"}.

Parameter

Type

Required

Description

Name

String

Yes

The name of the resource. The name can be up to 64 bytes in length and must be encoded in UTF-8. This parameter corresponds to NAME in the HTTP Live Streaming (HLS) V5 protocol.

Language

String

No

Optional. The language code in RFC 5646 format that corresponds to the `LANGUAGE` attribute of the HLS V5 protocol.

URI

String

Yes

The path of the resource.

Format: ^[a-z]{1}[a-z0-9./-]+$. Example: a/b/c/d/audio-1.m3u8.

Parameter

Type

Required

Description

MultiBitrateVideoStreams

JsonArray

Yes

The array of multiple streams. Example: [{"RefActivityName": "video-1","ExtXStreamInfo": {"BandWidth": "111110","Audio":"auds","Subtitles": "subs"}}].

Parameter

Type

Required

Description

BandWidth

String

Yes

The bandwidth. This parameter specifies the upper limit of the total bitrate and corresponds to BANDWIDTH in the HLS V5 protocol.

Audio

String

No

The ID of the audio stream group. This parameter corresponds to AUDIO in the HLS V5 protocol.

Subtitles

String

No

The ID of the subtitle stream group. This parameter corresponds to SUBTITLES in the HLS V5 protocol.

Parameter

Type

Required

Description

Group

String

Yes

The name of the group. Example:

<AdaptationSet group="videostreams" mimeType="video/mp4" par="4096:1744"
              minBandwidth="258157" maxBandwidth="10285391" minWidth="426" maxWidth="4096"
              minHeight="180" maxHeight="1744" segmentAlignment="true"
              startWithSAP="1">

Lang

String

No

The language of the resource. You can specify this parameter for audio and subtitle resources.

Parameter

Type

Required

Description

Id

String

Yes

The ID of the stream. Example:

<Representation id="240p250kbps" frameRate="24" bandwidth="258157"
              codecs="avc1.4d400d" width="426" height="180">

URI

String

Yes

The path of the resource. Format: ^[a-z]{1}[a-z0-9./-]+$. Example: a/b/c/d/video-1.mpd.

Parameter

Type

Required

Description

Format

String

Yes

The format of the input subtitle file. Valid values: stl, ttml, and vtt.

InputFile

String

Yes

{"Bucket":"example-bucket-****","Location":"oss-cn-hangzhou","Object":"example-logo****.png"}
              or
              {"URL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/subtitle/test****.chs.vtt"}

Name

Type

Required

Description

OutputFile

String

Yes

The storage address for video snapshot results.

Example: "{"Bucket":"test-bucket-****","Location":"oss-cn-shanghai","Object":"output{Count}.jpg"}".

The {Count} placeholder specifies the serial number of a snapshot. The snapshots are named output00001.jpg, output00002.jpg, and so on.

VideoCensor

String

No

Specifies whether to review the video content. Default value: true.

If you set this parameter to false, you must make sure that a job for the same media input file was submitted and successfully executed. Otherwise, the request is rejected.

BizType

String

No

Default value: common. Custom business type.

Scope

String

No

The following are the possible review results:

• abnormal: Includes only results with issues.

• all: Includes all results.

Default value: abnormal.