All Products
Document Center

ApsaraVideo VOD:SubmitSnapshotJob

Last Updated:Aug 04, 2023

Submits a snapshot job for a video and starts asynchronous snapshot processing.

Operation Description

  • Only snapshots in the JPG format are generated.
  • After a snapshot job is complete, ApsaraVideo VOD sends a SnapshotComplete event notification that contains EventType=SnapshotComplete and SubType=SpecifiedTime.
  • Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    • VOD

    Request parameters


    The ID of the video.


    The start time of the specified snapshot time period.

    • Unit: milliseconds.
    • Default value: 0.

    The width of each snapshot. Valid values: [8,4096]. By default, the width of the video mezzanine file is used. Unit: pixel.


    The height of each snapshot. Valid values: [8,4096]. By default, the height of the video mezzanine file is used. Unit: pixel.


    The maximum number of snapshots. Default value: 1.


    The snapshot interval. The value must be greater than or equal to 0. Unit: seconds. If you set this parameter to 0, snapshots are taken at even intervals based on the video duration divided by the value of the Count parameter. Default value: 1.


    The sprite snapshot configuration. If you set this parameter, sprite snapshots are generated. For more information, see SpriteSnapshotConfig.

    {'CellWidth': 120, 'CellHeight': 68, 'Columns': 3,'Lines': 10, 'Padding': 20, 'Margin': 50}

    The ID of the snapshot template.

    • We recommend that you create a snapshot template before you specify the ID of the snapshot template.
    • If you set the SnapshotTemplateId parameter, all the other request parameters except the Action and VideoId parameters are ignored.
    • For more information about how to create a snapshot template, see AddVodTemplate.

    The custom configurations, including the configuration of transparent data transmission and callback configurations. The value is a JSON-formatted string. For more information, see UserData.


    Note The callback configurations take effect only when you specify the HTTP callback URL and select the specific callback events in the ApsaraVideo VOD console.

    NoteYou must set at least one of the Count and Interval parameters. If you set both of them, the setting with fewer snapshots generated prevails.

    Response parameters


    Response result.


    The ID of the request.


    The information about the snapshot job.


    The ID of the snapshot job.



    Sample success responses


      "RequestId": "25818875-5F78-5EB0-4AF6-D7393642****",
      "SnapshotJob": {
        "JobId": "ad90a501b1b94b72374ad0050464****"

    Error codes

    For a list of error codes, visit the Service error codes.

    Common errors

    The following table describes the common errors that this operation can return.

    Error codeError messageHTTP status codeDescription
    InvalidVideo.NotFoundThe video does not exist.404The error message returned because the video does not exist.
    NoSuchResourceThe specified resource %s does not exist.404The error message returned because the specified resource does not exist.
    Forbidden.IllegalStatusStatus of the video is illegal.400The error message returned because the video status is invalid. You can submit a snapshot job for a video only when the video is in the UploadSucc, Normal, Checking, or Blocked state.