All Products
Search

This Product

    Intelligent Media Management:CreateHighlightTask

    Document Center

    Intelligent Media Management:CreateHighlightTask

    Last Updated:Jun 22, 2026

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

    Operation description

    • Before you use this operation, make sure that you fully understand the billing of Intelligent Media Management (IMM). For more information, see Billing overview. This operation incurs fees for highlight extraction and media processing.

    • Before you call this operation, make sure that a project already 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 None

    Request syntax

    POST  HTTP/1.1

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    ProjectName

    string

    Yes

    The project name.

    immtest
    Sources

    array<object>

    Yes

    The list of media resources to process. A maximum of 10 videos are supported.

    object

    No

    The media resource to process.

    URI

    string

    Yes

    The URI of the media resource (OSS URI). Only videos are supported.

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

    number

    No

    The start time of the media resource. Valid values: [0, video duration]. This parameter takes effect only when Type is set to Concat.

    0
    Duration

    number

    No

    The duration of the media clip. Unit: seconds. Default value: 0, which indicates the end of the video. This parameter takes effect only when Type is set to Concat.

    0
    Mode

    string

    No

    The highlight recognition mode. Valid values:

    • Scene: scene and frame recognition.

    • Average (default): average slice recognition.

    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:

    • Pets

    • People

    • Sports

    • Meetings

    The value cannot exceed 100 characters.

    character
    Edit

    object

    No

    The editing configuration.

    Mode

    string

    Yes

    The editing mode. Valid values:

    • Sequential: sequential mode.

    Sequential
    BackgroundMusicMode

    string

    No

    The background music mode. Default value: Closed. Valid values:

    • Random: custom background music, randomly selected based on weight.

    • Sequential: custom background music, applied in order.

    • Closed: no background music.

    Closed
    BackgroundMusics

    array<object>

    No

    The background music tracks. This parameter takes effect when BackgroundMusicMode is set to Random or Sequential. The maximum number is 1..

    object

    No

    The background music.

    URI

    string

    Yes

    The URI of the background music (OSS URI). Only audio files are supported.

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

    number

    No

    The volume intensity of the background music. Valid values: [0, 10]. Default value: 0.2. A value of 1 indicates the original volume.

    0.2
    TransitionMode

    string

    No

    The transition mode. Default value: Closed. Valid values:

    • Auto: automatic transition.

    • Random: custom transition, randomly selected based on weight.

    • Sequential: custom transition, applied in order.

    • Closed: no transition.

    Closed
    Transitions

    array<object>

    No

    The transition effects. This parameter takes effect when TransitionMode is set to Random or Sequential. A maximum of 10 transitions are supported.

    object

    No

    Transition

    string

    Yes

    The transition effect. For more information, see Transition effects.

    fade
    Duration

    number

    No

    The transition duration. Unit: seconds. If the transition duration is greater than the clip duration minus 1, the transition effect on that clip does not take effect. Valid values: [0, 5].

    0
    Weight

    integer

    No

    The transition weight. Valid values: [1, 100]. Default value: 50. This parameter takes effect when TransitionMode is set to Random.

    50
    VfxEffectMode

    string

    No

    The effect mode. Default value: Closed. Valid values:

    • Auto: automatic effect.

    • Random: custom effect, randomly selected based on weight.

    • Sequential: custom effect, applied in order.

    • Closed: no effect.

    Closed
    VfxEffects

    array<object>

    No

    The visual effects. This parameter takes effect when VfxEffectMode is set to Random or Sequential. A maximum of 10 effects are supported.

    object

    No

    VfxEffect

    string

    Yes

    The visual effect. For more information, see Effects.

    letterboxed
    Weight

    integer

    No

    The effect weight. Valid values: [1, 100]. Default value: 50. This parameter takes effect when VfxEffectMode is set to Random.

    50
    Output

    object

    Yes

    The output configuration.

    URI

    string

    Yes

    The URI of the output file.

    oss://test-bucket/test-target-object.mp4
    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, flv

    Important Container and URI must be specified together.
    .

    mp4
    Speed

    number

    No

    The playback speed of the media. Valid values: [0.5, 1.0]. Default value: 1.0.

    Note

    This value is 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
    Segment

    object

    No

    The media segmentation settings. By default, no segmentation is performed.

    Format

    string

    No

    The media segmentation format. Valid values:

    • hls

    • dash.

    hls
    Duration

    number

    No

    The segment duration. Unit: seconds.

    1
    StartNumber

    integer

    No

    The start number. Only hls is supported. Default value: 0.

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

    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.

    MaxDuration

    number

    No

    The maximum duration of the clipped video. Unit: seconds.

    10.0
    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 for and filter asynchronous tasks.

    {"test":"val1"}
    CredentialConfig CredentialConfig

    No

    The China authorization configuration. Leave this parameter empty unless you have specific requirements..

    Notification Notification

    No

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

    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.