API parameters for highlight montages - Intelligent Media Services

This topic describes the production parameters for highlight montages.

Important

Note: When you use this API, the region specified in the Object Storage Service (OSS) URL for all media assets must match the region of the OpenAPI endpoint that you call.
Supported regions: China (Shanghai), China (Beijing), China (Hangzhou), China (Shenzhen), US (West), and Singapore. The action label detection feature (corresponding to the EnableActionRecog and CustomActions parameters) is supported only in the China (Shanghai) region.
This version does not support video materials without human voices. Ensure that your video materials meet this requirement.
When you use the service, replace parameters such as [your-bucket], [your-region-id], [your-file-name], [your-file-path], and media asset IDs (for example, "****9d46c8b4548681030f6e****") in the examples with your actual values.

Usage notes

To create a highlight montage from multiple video materials and batch-produce videos with a single click, see SubmitScreenMediaHighlightsJob - Submit a highlight montage job. For more information about the key API parameters, see the InputConfig, EditingConfig, and OutputConfig parameter sections below.
To retrieve the details of a batch smart video production job, see GetBatchMediaProducingJob - Get information about a batch smart video production job.

InputConfig parameters

Configure InputConfig to specify the parameters for basic materials such as video footage, voiceovers, background music, and stickers.

Parameter	Type	Description	Example	Required
MediaArray	List<String>	Video materials for TV shows or movies. Only videos are supported. You can enter a list of media asset IDs or OSS URLs. The total duration of the videos cannot exceed two hours, and the maximum number of videos is 30. For more information about the supported video formats, see Video formats. Important Video materials without captions and human voices are not supported.	See Parameter examples.	Yes
HighlightStrategy	HighlightStrategy	The highlight montage policy.	See Parameter examples.	No
OpeningArray	List<Media>	Fixed opening clips. One clip is randomly selected for each production. You can enter a list of media asset IDs or OSS URLs. The maximum number of clips is 20. Images and videos are supported. For more information about supported formats, see Video formats and Image formats.	See Parameter examples.	No
EndingArray	List<Media>	Fixed ending clips. One clip is randomly selected for each production. You can enter a list of media asset IDs or OSS URLs. The maximum number of clips is 20. Images and videos are supported. For more information about supported formats, see Video formats and Image formats.	See Parameter examples.	No
TitleArray	List<String>	Titles. A maximum of 50 titles are supported. One title is randomly selected for each production. Each title can contain up to 50 characters.	["Hema Fresh in Huilongguan is now open","Hema Fresh is now open"]	No
SubHeadingArray	List<SubHeading>	Subheadings. Up to five levels of subheadings are supported.	See Parameter examples.	No
StickerArray	List<Sticker>	An array of stickers. One sticker is randomly selected for each production. A maximum of 50 stickers are supported. You can specify media asset IDs or OSS URLs. Randomization rule: Assume that you provide 10 stickers and set the number of output videos to 20. First, a random number from 1 to 10 is generated, for example, 3. Then, stickers are selected in the order of 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, and so on. For more information about supported formats, see Image formats.	See Parameter examples.	No
BackgroundMusicArray	List<String>	An array of background music tracks. One track is randomly selected for each production. A maximum of 50 tracks are supported. You can specify media asset IDs or OSS URLs. Randomization rule: Assume that you provide 10 background music tracks and set the number of output videos to 20. First, a random number from 1 to 10 is generated, for example, 3. Then, tracks are selected in the order of 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, and so on. For more information about supported formats, see Audio formats.	See Parameter examples.	No
BackgroundImageArray	List<String>	An array of background images. One image is randomly selected for each production. A maximum of 50 images are supported. You can specify media asset IDs or OSS URLs. Randomization rule: Assume that you provide 10 background images and set the number of output videos to 20. First, a random number from 1 to 10 is generated, for example, 3. Then, images are selected in the order of 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, and so on. For more information about supported formats, see Image formats.	See Parameter examples.	No

HighlightStrategy parameters

Parameter	Data type	Description	Example	Required
IntroConfig	JSON	Configuration for the beginning of the highlight section. Mode: The selection mode. Default value: Disabled. Auto: Automatically selects the most intense clip as the beginning. Disabled: No extra beginning is added.	{"Mode":"Disabled"}	No
TargetDurationConfig	TargetDurationConfig	Configuration for the output video duration.	{"TargetDuration": 180, "SpeedRange": [0.95, 1]}	No
PlotPacingType	String	The plot pacing of the highlight section. This parameter takes effect only when ThemeConfig.ThemeType is set to JumpHighlight. Valid values: Slow Normal Fast	Slow	No. Default value: Normal.
ThemeConfig	ThemeConfig	Configuration related to the editing theme.	{"ThemeType":"JumpHighlight" }	No
HighlightDescription	String	A description of the highlight extraction policy. This parameter takes effect only when ThemeConfig.ThemeType is set to SmoothHighlight.	Prioritize scenes with the following features. Obvious externalized emotions: The male protagonist directly expresses strong emotions through actions, such as anger, protection, or comeback (for example, the 'rivalry' between the male protagonist and his older brother). Strong contrast: Convey internal conflicts through contrasting behaviors or identities (such as power struggles or emotional tension). Concentrated plot conflicts: Focus on the protagonist's core conflicts, such as family feuds or disguised identities, to enhance viewer engagement. Prominent dramatic plots: Include bizarre dialogues or plot twists (such as 'a woman disguised as a man is recognized') to increase appeal and create buzz.	No
FaceInfo	FaceInfo	Set face information to help identify characters. If you want to feature certain characters more in the highlights, configure this parameter. This parameter takes effect only when ThemeConfig.ThemeType is set to SmoothHighlight.	{"ImageInfoList":[{"Name":"Ning X","ImageURL":"http://[your-cdn-domain]/[your-file-path]/face1.png"}]}	No
EnableActionRecog	Boolean	Specifies whether to enable action detection. If enabled, highlight clips are selected based on action detection results. Note Action detection is supported only in the China (Shanghai) region.	true	No. Default value: false.
CustomActions	List<String>	Custom action labels. The system prioritizes mapping based on the provided label names. Example: ["fighting","crying"]. The array can contain up to 50 labels. Each label can contain up to 5 characters. Note Action detection is supported only in the China (Shanghai) region.	["fighting","crying"]	No

ThemeConfig parameters

Parameter	Data type	Description	Example	Required
ThemeType	String	JumpHighlight: Jump-cut editing. Selects multiple highlight clips and concatenates them in chronological order. The resulting video may have plot jumps and is suitable for creating pure highlight reels. A task can generate only one video at a time. SmoothHighlight: Smooth-cut editing. Selects multiple highlight clips as openings, and then, starting from each opening, clips a segment of the original video with the length of TargetDuration. The system automatically removes duplicate clips and trims the beginning and end. The resulting videos have a more coherent plot, and multiple videos can be generated at once.	SmoothHighlight	No. Default value: JumpHighlight.

TargetDurationConfig parameters

Parameter

Data type

Description

Example

Required

TargetDuration

Float

The desired total duration of the highlight section (excluding fixed openings, endings, and the highlight section's beginning), in seconds. The actual duration may vary slightly. If you do not set this parameter, the duration is automatically adapted based on the plot.
The value must be greater than or equal to 5 seconds and less than or equal to the total duration of the source material.

180

SpeedRange

List<String>

The speed adjustment range.

If you want the output video to have a fixed speed, set the start and end values of the speed range to be the same. For example, [1.2, 1.2] sets the speed to 1.2x.

If you want the actual duration of the output video to be as close as possible to TargetDuration, you can set an acceptable speed range. For example:

Assume TargetDuration is 10 and SpeedRange is [0.95, 1]. The acceptable duration range calculated from SpeedRange is [10, 10.526] seconds. The logic for calculating the actual output video duration is as follows:
- If the actual clip duration is 10.5 seconds, which is within the acceptable range [10, 10.526], the speed is adjusted to approximately 0.9524x (10 / 10.5). The final video duration is 10 seconds.
- If the actual clip duration is 11 seconds, the speed is adjusted by the lower limit of SpeedRange, which is 0.95x. The final video duration is 11 seconds multiplied by 0.95, resulting in a duration of 10.45 seconds.

[0.95, 1]

FaceInfo parameters

Parameter	Type	Description	Required
ImageInfoList	List<ImageInfo>	A list of photos of the characters (faces). The list can contain up to 200 photos.	No

ImageInfo parameters

Parameter	Type	Description	Example	Required
Name	String	The name of the character (face).	Daniel	Yes
ImageURL	String	The storage address of the character's (face) photo. The URL must be accessible over the Internet. Make sure that the face image contains only one person, and the face is clear, without significant obstructions or missing parts.	http://[your-cdn-domain]/[your-file-path]/face1.png	Yes, one is required.
ImageId	String	The media asset ID of the image.	**9d46c886b45481030f6e**	Yes, one is required.

Media parameters

Parameter	Data type	Description	Example	Required
MediaId	String	The media asset ID.	**b4549dfvc88681030f6e**	You must specify one of the two. If both are specified, MediaId is used.
MediaURL	String	The URL of the media asset. Only self-managed OSS is supported.	Rule: http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-path]/[your-file-name]_{index}.mp4 Example: http://example.oss-cn-shanghai.aliyuncs.com/example/example_{index}.mp4
In	Float	When the material is a video, this is the in-point of the material, in seconds.	0	No
Out	Float	When the material is a video, this is the out-point of the material, in seconds.	5	No
Duration	Float	When the material is an image, this is the display duration of the material, in seconds.	2	No
DyncFrames	Integer	When the material is a GIF, this is the number of frames in the animated image.	25	No

Parameter examples

Smooth-cut editing

{
  "MediaArray": [
    "****9d46c8b42f4581030f6e****",
    "****9d46c8b4frtf81030f6e****",
    "****9d46c8b4asdf81030f6e****",
    "****9d46c8b43d3481030f6e****"
  ],
  "HighlightStrategy": {
    "IntroConfig": {
      "Mode": "Disabled"
    },
    "TargetDurationConfig": {
      "TargetDuration": 300
    },
    "ThemeConfig": {
      "ThemeType": "SmoothHighlight"
    },
    "HighlightDescription":"Prioritize scenes with the following features. Obvious externalized emotions: The male protagonist directly expresses strong emotions through actions, such as anger, protection, or comeback (for example, the 'rivalry' between the male protagonist and his older brother). Strong contrast: Convey internal conflicts through contrasting behaviors or identities (such as power struggles or emotional tension). Concentrated plot conflicts: Focus on the protagonist's core conflicts, such as family feuds or disguised identities, to enhance viewer engagement. Prominent dramatic plots: Include bizarre dialogues or plot twists (such as 'a woman disguised as a man is recognized') to increase appeal and create buzz.",
    "FaceInfo":{"ImageInfoList":[{"Name":"Ning X","ImageURL":"http://[your-cdn-domain]/[your-file-path]/face1.png"}]},
    "EnableActionRecog": true,
    "CustomActions": ["fighting","crying"]
  },
  "OpeningArray": [
    {
      "MediaId": "****9d46c8b4548681030f6e****",
      "In": 0,
      "Out": 5
    },
    {
      "MediaId": "****9d46c8b4548661030f6e****",
      "In": 0,
      "Out": 5
    }
  ],
  "EndingArray": [
    {
      "MediaId": "****9d46c8b4548681030f6e****",
      "In": 0,
      "Out": 5
    },
    {
      "MediaId": "****9d46c8b4548661030f6e****",
      "In": 0,
      "Out": 5
    }
  ],
  "TitleArray": [
    "Hema Fresh in Huilongguan is now open",
    "Hema Fresh is now open"
  ],
  "SubHeadingArray": [
    {
      "Level": 1,
      "TitleArray": [
        "Subheading 1",
        "Subheading 2"
      ]
    },
    {
      "Level": 3,
      "TitleArray": [
        "Level 3 subheading"
      ]
    }
  ],
  "StickerArray": [
    {
      "MediaId": "****9d46c8b4548681030f6e****",
      "X": 10,
      "Y": 100,
      "Width": 300,
      "Height": 300,
      "Opacity": 0.6
    },
    {
      "MediaURL": "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name].png",
      "X": 10,
      "Y": 100,
      "Width": 300,
      "Height": 300
    }
  ],
  "BackgroundMusicArray": [
    "****b4549d46c88681030f6e****",
    "****549d46c88b4681030f6e****",
    "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name].mp3"
  ],
  "BackgroundImageArray": [
    "****6c886b4549d481030f6e****",
    "****9d46c8548b4681030f6e****",
    "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name].png"
  ]
}

Jump-cut editing

{
  "MediaArray": [
    "****9d46c8b42f4581030f6e****",
    "****9d46c8b4frtf81030f6e****",
    "****9d46c8b4asdf81030f6e****",
    "****9d46c8b43d3481030f6e****"
  ],
  "HighlightStrategy": {
    "IntroConfig": {
      "Mode": "Disabled"
    },
    "ThemeConfig": {
      "ThemeType": "JumpHighlight"
    },
    "EnableActionRecog": true,
    "CustomActions": ["fighting","crying"]
  },
  "OpeningArray": [
    {
      "MediaId": "****9d46c8b4548681030f6e****",
      "In": 0,
      "Out": 5
    },
    {
      "MediaId": "****9d46c8b4548661030f6e****",
      "In": 0,
      "Out": 5
    }
  ],
  "EndingArray": [
    {
      "MediaId": "****9d46c8b4548681030f6e****",
      "In": 0,
      "Out": 5
    },
    {
      "MediaId": "****9d46c8b4548661030f6e****",
      "In": 0,
      "Out": 5
    }
  ],
  "TitleArray": [
    "Hema Fresh in Huilongguan is now open",
    "Hema Fresh is now open"
  ],
  "SubHeadingArray": [
    {
      "Level": 1,
      "TitleArray": [
        "Subheading 1",
        "Subheading 2"
      ]
    },
    {
      "Level": 3,
      "TitleArray": [
        "Level 3 subheading"
      ]
    }
  ],
  "StickerArray": [
    {
      "MediaId": "****9d46c8b4548681030f6e****",
      "X": 10,
      "Y": 100,
      "Width": 300,
      "Height": 300,
      "Opacity": 0.6
    },
    {
      "MediaURL": "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name].png",
      "X": 10,
      "Y": 100,
      "Width": 300,
      "Height": 300
    }
  ],
  "BackgroundMusicArray": [
    "****b4549d46c88681030f6e****",
    "****549d46c88b4681030f6e****",
    "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name].mp3"
  ],
  "BackgroundImageArray": [
    "****6c886b4549d481030f6e****",
    "****9d46c8548b4681030f6e****",
    "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name].png"
  ]
}

EditingConfig parameters

Configure EditingConfig to specify parameters such as volume, position, and other production settings for the output video.

Parameter	Type	Description	Example	Required
MediaConfig	JSON	Configuration for the input video materials.	See Parameter example.	No
TitleConfig	JSON	Configuration for titles. You can configure caption parameters.	See Parameter example.	No
SubHeadingConfig	JSON	Configuration for multi-level subheadings. You can set caption parameters. JSON field description: key: Level value: Banner text	See Parameter example.	No
BackgroundMusicConfig	JSON	Configuration for background music.	See Parameter example.	No
BackgroundImageConfig	JSON	Configuration for the background image. If a background image is already configured in InputConfig, this field does not take effect.	See Parameter example.	No
ProcessConfig	JSON	Configuration for montage processing.	See Parameter example.
FECanvas	JSON	Canvas configuration for frontend page previews.	{"Width": 1080,"Height": 1920}	No
ProduceConfig	JSON	Configuration for standard video editing and production. For more information about the fields, see: EditingProduceConfig	{"AutoRegisterInputVodMedia":true,"OutputWebmTransparentChannel":true,"CoverConfig":{"StartTime":3.3},"AudioChannelCopy":"left","PipelineId":"xxxd54a97cff4108b555b01166d4bxxx","MaxBitrate":5000,"KeepOriginMaxBitrate":false,"KeepOriginVideoMaxFps":false}	No

ProcessConfig parameters

Parameter	Type	Description	Example	Required
AllowVfxEffect	Boolean	Specifies whether to allow special effects.	true	No. Default value: false.
VfxEffectProbability	Float	The probability of applying a special effect to each video clip. Value range: 0.0 to 1.0. Supports up to two decimal places.	0.6	No. Default value: 0.5.
VfxFirstClipEffectList	List<String>	If VfxFirstClipEffectList is not empty, the special effect for the first clip of the output video is selected from this list. If VfxFirstClipEffectList is empty, the special effect for the first clip is randomly selected from the following: "slightshow", "starfieldshinee", "starfieldshinee2", "starsparkle", "colorfulripples", and "starfield". For examples of special effects, see: Special effect examples.	["slightshow","starfieldshinee"]	No
VfxNotFirstClipEffectList	List<String>	If VfxNotFirstClipEffectList is not empty, the special effects for clips other than the first one are selected from this list. If VfxNotFirstClipEffectList is empty, the special effects for clips other than the first one are selected from the following: "zoomslight", "zoom", "zoominout", and "slightshake". For examples of special effects, see: Special effect examples.	["zoomslight","zoom"]	No
AllowTransition	Boolean	Specifies whether to allow transitions.	true	No. Default value: false.
TransitionDuration	Float	The duration of the transition, in seconds. If the transition duration is greater than the clip duration minus 1, the transition effect for that clip does not take effect.	0.5	No. Default value: 0.5 seconds.
TransitionList	List<String>	A list of custom transition effects. When AllowTransition is true, a transition effect is randomly selected from this list for production. For the available transition effects, see Transition effect library. If this parameter is empty, a transition is randomly selected from the following: "linearblur", "colordistance", "crosshatch", "dreamyzoom", and "doomscreentransition_up".	["directional", "linearblur"]	No
UseUniformTransition	Boolean	Specifies whether to use the same transition effect throughout a single output video.	true	No. Default value: true.
AllowFilter	Boolean	Specifies whether to allow custom filters.	false	No. Default value: false.
FilterList	List<String>	A list of custom filter effects. When AllowFilter is true, a filter is randomly selected from this list for production. For available filter effects, see Filter effect examples. If this parameter is empty, no filter effect is added.	["m1", "m2"]	No

Parameter example

{
  "MediaConfig": {
    "Volume": 0 // Mute the source video material by default.
  },
  "TitleConfig": {
    "Alignment": "TopCenter",
    "AdaptMode": "AutoWrap",
    "Font": "Alibaba PuHuiTi 2.0 95 ExtraBold",
    "SizeRequestType": "Nominal",
    "Y": 0.1, // The Y-coordinate of the title when the output video is in portrait mode.
    "Y": 0.05, // The Y-coordinate of the title when the output video is in landscape mode.
    "Y": 0.08 // The Y-coordinate of the title when the output video is in square mode.
  },
   "SubHeadingConfig": {
    "1": {
      "Y": 0.3,
      "FontSize": 40
    },
    "3": {
      "Y": 0.5,
      "FontSize": 30
    }
  },
  "BackgroundMusicConfig": {
    "Volume": 0.2,   // Set the background music volume to 20% by default.
    "Style": null
  },
  "ProcessConfig": {
    "AllowVfxEffect": false,	  // Specifies whether to add special effects.
    "AllowTransition": false,	  // Specifies whether to add transitions.
  }
}

TemplateConfig parameters

TemplateConfig contains common parameters for one-click video production and is used to configure a video production template. For detailed parameter descriptions and usage examples, see TemplateConfig parameters.

OutputConfig parameters

Configure OutputConfig to specify production parameters such as the output address, naming rules, width and height, and the number of output videos.

Parameter	Type	Description	Example	Required
MediaURL	String	The output video address. It must contain the placeholder {index}.	Rule: http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-path]/[your-file-name]_{index}.mp4 Example: http://example.oss-cn-shanghai.aliyuncs.com/example/example_{index}.mp4	Required when GeneratePreviewOnly is false and the output video is delivered to OSS.
StorageLocation	String	Specifies the storage address for the media asset file to be output to VOD.	Rule: [your-vod-bucket].oss-[your-region-id].aliyuncs.com Example: outin-**6c886b4549d481030f6e**.oss-cn-shanghai.aliyuncs.com	Required when GeneratePreviewOnly is false and the output video is delivered to VOD.
FileName	String	The output file name. It must contain the placeholder {index}.	Rule: [your-file-name]__{index}.mp4 Example: example_{index}.mp4	Required when GeneratePreviewOnly is false and the output video is delivered to VOD.
GeneratePreviewOnly	Boolean	If GeneratePreviewOnly is set to true, the current task only generates a timeline for preview and does not actually produce the video. You do not need to specify the output video address. After the one-click video production task is complete, query the task result using GetBatchMediaProducingJob. The returned sub-task list will contain the editing project ID (projectId). You can then call GetEditingProject to get the preview timeline.	false	No. Default value: false.
Count	Integer	The number of output videos. When ThemeConfig.ThemeType is JumpHighlight, Count can only be 1. When ThemeConfig.ThemeType is SmoothHighlight, the number of generated videos is less than or equal to Count. The actual number of videos depends on the number of highlight clips. The value of Count ranges from 1 to 100.	1	No. Default value: 1.
Width	Integer	The width of the output video, in px.	1080	Yes
Height	Integer	The height of the output video, in px.	1920	Yes
Video	JSONObject	Configuration for the output video stream, such as Crf and Codec.	{"Crf": 27}	No

Parameter example

{
 	"MediaURL": "http://[your-bucket].oss-[your-region-id].aliyuncs.com/[your-file-name]_{index}.mp4",
 	"Count": 1,
 	"Width": 1080,
 	"Height": 1920,
 	"Video": {"Crf": 27},
        "GeneratePreviewOnly":false
}

Processing logic

Configure the editing materials using MediaArray. The materials are analyzed and processed in the order they are provided.
Configure the opening and ending of the highlight reel section using HighlightStrategy.
Configure the fixed opening (pre-roll) before the highlight reel section and the fixed ending (post-roll) after it using OpeningArray and EndingArray.
Parameters in the one-click video production API call take precedence over parameters set in a template. If you configure TemplateConfig, the system first reads non-empty parameters from the API call. For any empty parameters, the system reads the values from the template.

Intelligent Media Services:Highlight montage

Usage notes

InputConfig parameters

HighlightStrategy parameters

ThemeConfig parameters

TargetDurationConfig parameters

FaceInfo parameters

ImageInfo parameters

Media parameters

Parameter examples

Smooth-cut editing

Jump-cut editing

EditingConfig parameters

ProcessConfig parameters

Parameter example

TemplateConfig parameters

OutputConfig parameters

Parameter example

Processing logic

References