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.
Debugging
Authorization information
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
VideoId | string | Yes | The ID of the video. You can use one of the following methods to obtain the ID:
| d3e680e618708efbf2cae7cc9312**** |
SpecifiedOffsetTime | long | No | The point in time when the first snapshot is captured.
| 0 |
Width | string | No | The width of each snapshot. Valid values: | 1280 |
Height | string | No | The height of each snapshot. Valid values: | 720 |
Count | long | No | The maximum number of snapshots. Default value: 1. | 1 |
Interval | long | No | The snapshot interval. The value must be greater than or equal to 0.
| 1 |
SpriteSnapshotConfig | string | No | 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} |
SnapshotTemplateId | string | No | The ID of the snapshot template.
| f5b228fe693bf55bd87b789**** |
UserData | string | No | 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.
| {"MessageCallback":{"CallbackURL":"http://.example.aliyundoc.com"},"Extend":{"localId":"xxx","example":"www"}} |
SpecifiedOffsetTimes | array | No | The playback positions at which you want to capture snapshots. Unit: milliseconds. You can specify up to 30 playback positions in a request. | |
long | No | The custom playback position at which you want to capture the snapshot. Unit: milliseconds. | 1000 |
Response parameters
Examples
Sample success responses
JSON
format
{
"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 time | Summary of changes | Operation |
---|---|---|
2023-12-15 | The request parameters of the API has changed | View Change Details |
Common errors
The following table describes the common errors that this operation can return.
Error code | Error message | HTTP status code | Description |
---|---|---|---|
InvalidVideo.NotFound | The video does not exist. | 404 | The error message returned because the video does not exist. |
NoSuchResource | The specified resource %s does not exist. | 404 | The error message returned because the specified resource does not exist. |
Forbidden.IllegalStatus | Status of the video is illegal. | 400 | The 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. |