All Products
Document Center

ApsaraVideo VOD:SubmitSnapshotJob

Last Updated:May 22, 2024

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 is captured, the SnapshotComplete callback is fired and EventType=SnapshotComplete, SubType=SpecifiedTime is returned.

QPS limits

You can call this operation up to 30 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limits.


OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

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
  • All Resources

Request parameters


The ID of the video. You can use one of the following methods to obtain the ID:

  • After you upload a video in the ApsaraVideo VOD console, you can log on to the ApsaraVideo VOD console and choose Media Files > Audio/Video to view the ID of the video.
  • Obtain the video ID from the response to the CreateUploadVideo operation that you called to obtain the upload URL and credential.
  • Obtain the video ID from the response to the SearchMedia operation that you called to query media information after the audio or video file is uploaded.

The point in time when the first snapshot is captured.

  • Unit: milliseconds.
  • Default value: 0.

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


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


The maximum number of snapshots. Default value: 1.


The snapshot interval. The value must be greater than or equal to 0.

  • Unit: seconds.
  • Default value: 1.
  • If you set this parameter to 0, snapshots are captured at even intervals based on the video duration divided by the value of the Count parameter.

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 template ID. For more information about how to create a snapshot template, see AddVodTemplate .
  • If you set the SnapshotTemplateId parameter, all the other request parameters except the Action and VideoId parameters are ignored.

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

Note To use the message callback feature, you must specify an HTTP callback URL and the callback events in the ApsaraVideo VOD console. Otherwise, the callback settings do not take effect.

The playback positions at which you want to capture snapshots. Unit: milliseconds. You can specify up to 30 playback positions in a request.


The custom playback position at which you want to capture the snapshot. Unit: milliseconds.

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

Response parameters


The returned results.


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.

Change history

Change timeSummary of changesOperation
2023-12-15The request parameters of the API has changedsee changesets
Change itemChange content
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: SpecifiedOffsetTimes

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.