All Products
Search

This Product

    Intelligent Media Services:SubmitSnapshotJob

    Document Center

    Intelligent Media Services:SubmitSnapshotJob

    Last Updated:Mar 30, 2026

    Submits a snapshot job.

    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

    ice:SubmitSnapshotJob

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    Name

    string

    No

    The name of the job.

    SampleJob
    Input

    object

    Yes

    The snapshot input.

    Type

    string

    Yes

    The type of the input file. Valid values:

    1. OSS: an Object Storage Service (OSS) object.

    2. Media: a media asset.

    Media
    Media

    string

    Yes

    The input file. If Type is set to OSS, the URL of an OSS object is returned. If Type is set to Media, the ID of a media asset is returned. The URL of an OSS object can be in one of the following formats:

    1. oss://bucket/object

    2. http(s)://bucket.oss-[RegionId].aliyuncs.com/object In the URL, bucket specifies an OSS bucket that resides in the same region as the job, and object specifies the object URL in OSS.

    Note

    Before you use the OSS bucket in the URL, you must add the bucket on the Storage Management page of the Intelligent Media Services (IMS) console.

    oss://bucket/object.mp4
    Output

    object

    Yes

    The snapshot output.

    Type

    string

    Yes

    The type of the output file. Valid values:

    1. OSS: an OSS object.

    2. Media: a media asset.

    OSS
    Media

    string

    Yes

    The output file. If Type is set to OSS, the URL of an OSS object is returned. If Type is set to Media, the ID of a media asset is returned. The URL of an OSS object can be in one of the following formats:

    1. oss://bucket/object

    2. http(s)://bucket.oss-[RegionId].aliyuncs.com/object

    In the URL, bucket specifies an OSS bucket that resides in the same region as the job, and object specifies the object URL in OSS. If multiple static snapshots were captured, the object must contain the "{Count}" placeholder. In the case of a sprite, the object must contain the "{TileCount}" placeholder. The suffix of the WebVTT snapshot objects must be ".vtt".

    Note

    Before you use the OSS bucket in the URL, you must add the bucket on the Storage Management page of the IMS console.

    oss://test-bucket/output-{Count}.jpg
    TemplateConfig

    object

    Yes

    The snapshot template configuration.

    TemplateId

    string

    Yes

    The template ID.

    ****96e8864746a0b6f3****

    OverwriteParams

    object

    No

    The parameters that are used to overwrite the corresponding parameters.

    Type

    string

    No

    The snapshot type. Valid values:

    Sprite
    FrameType

    string

    No

    The type of the frame.

    intra
    Count

    integer

    No

    The number of snapshots.

    5
    Interval

    integer

    No

    The interval at which snapshots are captured.

    10
    Time

    integer

    No

    The point in time at which the system starts to capture snapshots in the input video.

    1000
    Width

    integer

    No

    The width of a captured snapshot.

    720
    Height

    integer

    No

    The height of a captured snapshot.

    480
    BlackLevel

    integer

    No

    The threshold that is used to filter out black frames for the first snapshot to be captured. This feature is available if you request the system to capture multiple snapshots.

    30
    PixelBlackThreshold

    integer

    No

    The color value threshold that determines whether a pixel is black.

    70
    SpriteSnapshotConfig

    object

    No

    The configuration of the sprite snapshot.

    CellWidth

    integer

    No

    The width of a single snapshot before tiling. The default value is the width of the output snapshot.

    720
    CellHeight

    integer

    No

    The height of a single snapshot before tiling. The default value is the height of the output snapshot.

    480
    Padding

    integer

    No

    The spacing between two adjacent snapshots. Default value: 0. Unit: pixels.

    20
    Margin

    integer

    No

    The width of the frame. Default value: 0. Unit: pixels.

    20
    Columns

    integer

    No

    The number of columns that the image sprite contains.

    20
    Lines

    integer

    No

    The number of rows that the image sprite contains.

    20
    Color

    string

    No

    The background color.

    #000000
    IsSptFrag

    boolean

    No

    The WebVTT snapshot configuration that specifies whether to merge the output snapshots.

    true
    ScheduleConfig

    object

    No

    The scheduling settings.

    PipelineId

    string

    No

    The ID of the ApsaraVideo Media Processing (MPS) queue that is used to run the job.

    ****96e8864746a0b6f3****

    UserData

    string

    No

    The user-defined data.

    {"test parameter": "test value"}

    Response elements

    Element

    Type

    Description

    Example

    object

    PlainResponse

    RequestId

    string

    The request ID.

    ******11-DB8D-4A9A-875B-275798******
    JobId

    string

    The job ID.

    ****20b48fb04483915d4f2cd8ac****

    Examples

    Success response

    JSON format

    {
  "RequestId": "******11-DB8D-4A9A-875B-275798******",
  "JobId": "****20b48fb04483915d4f2cd8ac****"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.