CreateHighlightTask - Intelligent Media Management - Alibaba Cloud Documentation Center

Creates a video highlight task. This feature is in invitational preview.

Operation description

Before you call this operation, make sure that you fully understand the billing methods and pricing of Intelligent Media Management (IMM). Fees are charged for highlight extraction and media processing.
Before you call this operation, make sure that an available project exists in the current region. For more information, see Project management.
Important Asynchronous tasks do not guarantee timeliness.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

imm:CreateHighlightTask

create

*Project

acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}

None

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
ProjectName	string	Yes	The name of the project.	immtest
Sources	array<object>	Yes	The list of media resources to be processed. You can specify up to 10 videos.
	object	No	The media resource to be processed.
Duration	number	No	The duration of the media clip. Unit: seconds. Default value: 0, which indicates the end time of the video. This parameter is valid only when Type is set to Concat.	0
StartTime	number	No	The start time of the media resource. Valid values: [0, video duration]. This parameter is valid only when Type is set to Concat. Unit: seconds.	0
URI	string	Yes	The URI of the media resource, which is an OSS URI. Only videos are supported.	oss://test-bucket/test-object
Mode	string	No	The highlight recognition mode. Valid values: Scene: scene and frame recognition Average: average clip recognition Default value: Average.	Average
Type	string	Yes	The processing type. Valid values: Retrieval: highlight extraction Concat: video composition Compose: one-click video creation	Retrieval
Highlight	object	No	The highlight configuration.
Content	string	Yes	The highlight content. Valid values: Pet Person Sports Meeting The value cannot exceed 100 characters in length.	character
Edit	object	No	The editing configuration.
BackgroundMusicMode	string	No	The background music mode. Valid values: Random: custom background music, randomly selected based on weights Sequential: custom background music, applied in sequence Closed: no background music Default value: Closed.	Closed
BackgroundMusics	array<object>	No	The background music. This parameter is valid only when BackgroundMusicMode is set to Random or Sequential. The current maximum number of background music tracks is 1.
	object	No	The background music track.
URI	string	Yes	The URI of the background music, which is an OSS URI. Only audio files are supported.	oss://test-bucket/test-object/test.mp3
Volume	number	No	The volume of the background music. Valid values: [0, 10]. Default value: 0.2. A value of 1 indicates the original volume.	0.2
Mode	string	Yes	The editing mode. Valid values: Sequential: sequential mode	Sequential
TransitionMode	string	No	The transition mode. Valid values: Auto: automatic transition Random: custom transition, randomly selected based on weights Sequential: custom transition, applied in sequence Closed: no transition Default value: Closed.	Closed
Transitions	array<object>	No	The transition effects. This parameter is valid only when TransitionMode is set to Random or Sequential. You can specify up to 10 transition effects.
	object	No
Duration	number	No	The duration of the transition. Unit: seconds. If the transition duration is greater than the clip duration minus 1, the transition effect on the clip does not take effect. Valid values: [0, 5].	0
Transition	string	Yes	The transition effect. For more information, see Transition effects.	fade
Weight	integer	No	The weight of the transition. Valid values: [1, 100]. Default value: 50. This parameter is valid only when TransitionMode is set to Random.	50
VfxEffectMode	string	No	The visual effect mode. Valid values: Auto: automatic visual effect Random: custom visual effect, randomly selected based on weights Sequential: custom visual effect, applied in sequence Closed: no visual effect Default value: Closed.	Closed
VfxEffects	array<object>	No	The visual effects. This parameter is valid only when VfxEffectMode is set to Random or Sequential. You can specify up to 10 visual effects.
	object	No
VfxEffect	string	Yes	The visual effect. For more information, see Visual effects.	letterboxed
Weight	integer	No	The weight of the visual effect. Valid values: [1, 100]. Default value: 50. This parameter is valid only when VfxEffectMode is set to Random.	50
Output	object	Yes	The output configuration.
Audio	TargetAudio	No	The audio processing parameter settings. Important If Audio is empty, the first audio stream (if any) is directly copied to the output file.
Container	string	No	The media container type. This parameter is required when Type is set to Concat or Compose. Valid values: Audio and video containers: mp4, mkv, mov, asf, avi, mxf, ts, and flv Important You must specify both Container and URI.	mp4
MaxDuration	number	No	The maximum duration of the edited video. Unit: seconds.	10.0
Segment	object	No	The media segmentation settings. By default, segmentation is not performed.
Duration	number	No	The length of each segment. Unit: seconds.	1
Format	string	No	The media segmentation format. Valid values: hls dash	hls
StartNumber	integer	No	The start number. This parameter is supported only for hls. Default value: 0.	0
Speed	number	No	The playback speed multiplier for the media. Valid values: [0.5, 1.0]. Default value: 1.0. Note The ratio of the default playback speed of the transcoded media file to that of the source media file. This is not speed-adjusted transcoding.	1.0
TargetDuration	number	No	The target duration of the video. Unit: seconds.	10.0
URI	string	Yes	The URI of the output file.	oss://test-bucket/test-target-object.mp4
Video	TargetVideo	No	The video processing parameter settings. Important If Video is empty, the first video stream (if any) is directly copied to the output file.
UserData	string	No	The custom user data, which is returned in asynchronous message notifications.	{"ID": "testuid","Name": "test-user","Avatar": "http://test.com/testuid"}
Tags	object	No	The custom tags used to search and filter asynchronous tasks.	{"test":"val1"}
CredentialConfig	CredentialConfig	No	The chained authorization configuration. Leave this parameter empty unless otherwise required.
Notification	Notification	No	The message notification configuration. For more information, see Notification. For the format of asynchronous notification messages, see Asynchronous notification message format.

Response elements

Element	Type	Description	Example
	object	Schema of Response
EventId	string	The event ID.	0ED-1Bz8z71k5TtsUejT4UJ16Es****
RequestId	string	The request ID.	CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6
TaskId	string	The task ID.	Highlight-4d51241b-04d4-4343-aa25-****

Examples

Success response

JSON format

{
  "EventId": "0ED-1Bz8z71k5TtsUejT4UJ16Es****",
  "RequestId": "CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6",
  "TaskId": "Highlight-4d51241b-04d4-4343-aa25-****"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.