All Products
Search

This Product

    Intelligent Media Management:CreateHighlightTask

    Document Center

    Intelligent Media Management:CreateHighlightTask

    Last Updated:Mar 13, 2026

    Creates a highlight task.

    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 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

    A list of media resources to process. You can specify up to 10 videos.

    object

    No

    The media resource to process.

    URI

    string

    Yes

    The URI of the media resource. Only OSS URIs are supported. Currently, only videos are supported.

    oss://test-bucket/test-object
    StartTime

    number

    No

    The start time of the media resource. The value must be within the range of [0, video duration]. This parameter is valid only when Type is set to Concat.

    0
    Duration

    number

    No

    The duration of the media segment in seconds. The default value is 0, which indicates that the segment ends at the end of the video. This parameter is valid only when Type is set to Concat.

    0
    Mode

    string

    No

    The highlight detection mode.

    • Scene: Detects highlights based on scenes and frames.

    • Average (default): Detects highlights based on average segmentation.

    Average
    Type

    string

    Yes

    The processing type.

    • Retrieval: Extracts highlights.

    • Concat: Concatenates videos.

    • Compose: Creates a video with one click.

    Retrieval
    Highlight

    object

    No

    The highlight configuration.

    Content

    string

    Yes

    The highlight content. Valid values:

    • pet

    • character

    • sports

    • meeting

    The value can be up to 100 characters in length.

    character
    Edit

    object

    No

    The video editing configuration.

    Mode

    string

    Yes

    The video editing mode.

    • Sequential: sequential mode

    Sequential
    BackgroundMusicMode

    string

    No

    The background music mode. The default value is Closed.

    • Random: Selects custom background music randomly based on weight.

    • Sequential: Applies custom background music in sequence.

    • Closed: No background music.

    Closed
    BackgroundMusics

    array<object>

    No

    The background music. This parameter is valid when BackgroundMusicMode is set to Random or Sequential. The maximum number of background music files is 1.

    object

    No

    The background music.

    URI

    string

    Yes

    The URI of the background music. Only OSS URIs are supported. Currently, only audio files are supported.

    oss://test-bucket/test-object/test.mp3
    Volume

    number

    No

    The volume of the background music. The value must be within the range of [0, 10]. The default value is 0.2. A value of 1 indicates the original volume.

    0.2
    TransitionMode

    string

    No

    The transition mode. The default value is Closed.

    • Auto: Applies transitions automatically.

    • Random: Selects custom transitions randomly based on weight.

    • Sequential: Applies custom transitions in sequence.

    • Closed: No transitions.

    Closed
    Transitions

    array<object>

    No

    The transition effects. This parameter is valid when TransitionMode is set to Random or Sequential. You can specify up to 10 transition effects.

    object

    No

    Transition

    string

    Yes

    The transition effect. For more information, see List of transitions.

    fade
    Duration

    number

    No

    The duration of the transition in seconds. If the transition duration is greater than the segment duration minus 1, the transition effect is not applied to the segment. The value must be within the range of [0, 5].

    0
    Weight

    integer

    No

    The weight of the transition. The value must be within the range of [1, 100]. The default value is 50. This parameter is valid when TransitionMode is set to Random.

    50
    VfxEffectMode

    string

    No

    The visual effect mode. The default value is Closed.

    • Auto: Applies visual effects automatically.

    • Random: Selects custom visual effects randomly based on weight.

    • Sequential: Applies custom visual effects in sequence.

    • Closed: No visual effects.

    Closed
    VfxEffects

    array<object>

    No

    The visual effects. This parameter is valid 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 List of effects.

    letterboxed
    Weight

    integer

    No

    The weight of the visual effect. The value must be within the range of [1, 100]. The default value is 50. This parameter is valid when VfxEffectMode is set to Random.

    50
    Output

    object

    Yes

    The output configuration.

    URI

    string

    Yes

    The path of the output file.

    oss://test-bucket/test-target-object.mp4
    Container

    string

    No

    This parameter is required when Type is set to Concat or Compose. The container format of the media file. Valid values for audio and video containers:

    • mp4, mkv, mov, asf, avi, mxf, ts, and flv

    Important You must set both the Container and URI parameters.

    mp4
    Speed

    number

    No

    The playback speed of the media file. The value must be within the range of [0.5, 1.0]. The default value is 1.0.

    Note

    This parameter specifies the ratio of the playback speed of the transcoded media file to that of the source media file. It does not perform speed transcoding.

    1.0
    Segment

    object

    No

    The media segment settings. By default, the media file is not segmented.

    Format

    string

    No

    The media segmentation method. Valid values:

    • hls

    • dash

    hls
    Duration

    number

    No

    The duration of each segment in seconds.

    1
    StartNumber

    integer

    No

    The starting ordinal number. This parameter is valid only for HLS. The default value is 0.

    0
    Video TargetVideo

    No

    The video processing parameters.

    Important If you leave Video empty, the first video stream, if it exists, is directly copied to the output file.

    Audio TargetAudio

    No

    The audio processing parameters.

    Important If you leave Audio empty, the first audio stream, if it exists, is directly copied to the output file.

    MaxDuration

    number

    No

    The maximum duration of the edited video in seconds.

    10.0
    UserData

    string

    No

    The custom information. This information is returned in the asynchronous notification message.

    {"ID": "testuid","Name": "test-user","Avatar": "http://test.com/testuid"}
    Tags

    object

    No

    The custom tags. You can use these tags to search for and filter asynchronous tasks.

    {"test":"val1"}
    CredentialConfig CredentialConfig

    No

    The chained authorization configuration. If you do not have special requirements, leave this parameter empty.

    Notification Notification

    No

    The notification configuration. For more information, click Notification. For information about the format of asynchronous notification messages, see Asynchronous notification message examples.

    Response elements

    Element

    Type

    Description

    Example

    object

    Schema of Response

    RequestId

    string

    The request ID.

    CA995EFD-083D-4F40-BE8A-BDF75FFFE0B6
    EventId

    string

    The event ID.

    0ED-1Bz8z71k5TtsUejT4UJ16Es****
    TaskId

    string

    The task ID.

    Highlight-4d51241b-04d4-4343-aa25-****

    Examples

    Success response

    JSON format

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

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.