All Products
Search

This Product

    Intelligent Media Services:Smart segmentation

    Document Center

    Intelligent Media Services:Smart segmentation

    Last Updated:Dec 15, 2025

    This topic describes how to use the SubmitSegmentationJob operation to perform smart segmentation. It also describes the response parameters that are returned when you call the GetSmartHandleJob operation to retrieve the results of a smart segmentation Job. For more information about billing, see Billing of smart segmentation.

    Important

    • Note: The region specified in the OSS URL of a media asset must be the same as the region of the OpenAPI endpoint that you call.

    • Supported regions: China (Shanghai), China (Beijing), China (Hangzhou), China (Shenzhen), US (West), and Singapore.

    Usage notes

    JobParams parameters

    You can configure JobParams to specify the policy for video shot segmentation.

    Parameter

    Type

    Description

    Required

    Mode

    String

    The segmentation mode. Valid values:

    • UserDefined: Custom segmentation. The video is segmented based on the time ranges specified in Ranges.

    • BasicClipSplit: Basic shot segmentation. The video is segmented based on scene changes.

    Yes

    Ranges

    List<Range>

    The time ranges for custom segmentation. This parameter is required when Mode is set to UserDefined.

    No

    Range parameters

    Parameter

    Type

    Description

    Required

    In

    Float

    The start time of the segment. Unit: seconds. Example: 0.

    Yes

    Out

    Float

    The end time of the segment. Unit: seconds. Example: 10.

    Yes

    Parameter example

    {
  "Mode": "UserDefined",
  "Ranges": [
    {
      "In": 0,
      "Out": 10
    },
    {
      "In": 20,
      "Out": 30
    }
  ]
}

    InputConfig parameters

    You can configure InputConfig to specify the source video material.

    Parameter

    Type

    Description

    Required

    Type

    String

    The media type. Select one of the following types:

    • OSS: The URL of an OSS object.

    • Media: The ID of a media asset.

    Yes

    Media

    String

    • If Type is set to OSS, OSS URLs and HTTP URLs are supported. Custom domain names are not supported. Examples: oss://test-bucket/test.mp4 or http://test-bucket.oss-cn-beijing.aliyuncs.com/test.mp4

    • If Type is set to Media, specify the media ID. Example: c5c62d8f0******cab312dce8e77dc6d.

    Yes

    Parameter example

    {
  "Type": "Media",
  "Media": "c5c62d8f0*********12dce8e77dc6d"
}

    OutputConfig parameters

    You can configure OutputConfig to specify parameters such as the output address and naming rules.

    Parameter

    Type

    Description

    Required

    Example

    OutputMediaTarget

    String

    The target type of the output file.

    • oss-object (an OSS object in your Alibaba Cloud OSS bucket).

    Yes

    oss-object

    Endpoint

    String

    The endpoint that complies with the S3 protocol.

    • For OSS, the region must be the same as the region of the service you access.

    The default value is the OSS endpoint of the same region.

    No

    https://oss-cn-shanghai.aliyuncs.com

    Bucket

    String

    The storage bucket that complies with the S3 protocol.

    • Your own OSS storage bucket.

    Yes

    test-output

    ObjectKey

    String

    The object name that complies with the S3 protocol.

    Supported placeholder:

    • {index}: This placeholder must be included in the file path.

    Yes

    dir/to/testOutput_{index}.mp4

    ExportAsNewMedia

    Boolean

    Specifies whether to export the output as a new media asset.

    This parameter is valid only when OutputMediaTarget is set to oss-object.

    No. The default value is false.

    false

    Width

    Integer

    The width of the output video. Unit: px. If you do not specify this parameter, the width of the source video is used.

    No

    1280

    Height

    Integer

    The height of the output video. Unit: px. If you do not specify this parameter, the height of the source video is used.

    No

    720

    Video

    JSONObject

    The configurations of the output video stream, such as Crf and Codec.

    No

    {

    "Bitrate": 3000

    }

    Parameter example

     {
    "OutputMediaTarget": "oss-object",
    "Endpoint": "https://oss-cn-shanghai.aliyuncs.com",
    "Bucket": "test-output",
    "ObjectKey": "dir/to/testOutput_{index}.mp4",
    "ExportAsNewMedia": false,
    "Width": 1280,
    "Height": 720,
    "Video": {
      "Bitrate": 3000
    }
  }

    GetSmartHandleJob response parameters

    You can call the GetSmartHandleJob operation to retrieve the results of a smart segmentation Job. The following section describes the parameters in AiResult:

    AiResult parameters

    {
  "SegmentationResult": {
    "OutputEndpoint": "http://oss-cn-shanghai.aliyuncs.com", // The endpoint that complies with the S3 protocol
    "OutputBucket": "test-output", // The bucket that complies with the S3 protocol
    "OutputObjectResults": [ // The results after shot segmentation
      {
        "ObjectKey": "testOutput_0.mp4", // The object name that complies with the S3 protocol
        "MediaId": "xxx1" // The ID of the media asset generated after shot segmentation
      },
       {
        "ObjectKey": "testOutput_0.mp4",
        "MediaId": "xxx2"
      }
    ]
  }
}

    References