Submits a snapshot job for a video and starts asynchronous snapshot processing.
- 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.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | SubmitSnapshotJob |
The operation that you want to perform. Set the value to SubmitSnapshotJob. |
VideoId | String | Yes | d3e680e618708*****efbf2cae7cc931 |
The ID of the video. |
SpecifiedOffsetTime | Long | No | 0 |
The start time of the specified snapshot time period.
|
Width | String | No | 1280 |
The width of each snapshot. Valid values: |
Height | String | No | 720 |
The height of each snapshot. Valid values: |
Count | Long | No | 1 |
The maximum number of snapshots. Default value: 1. |
Interval | Long | No | 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. |
SpriteSnapshotConfig | String | No | {'CellWidth': 120, 'CellHeight': 68, 'Columns': 3,'Lines': 10, 'Padding': 20, 'Margin': 50} |
The sprite snapshot configuration. If you set this parameter, sprite snapshots are generated. For more information, see SpriteSnapshotConfig. |
SnapshotTemplateId | String | No | f5b228fe693*****bf55bd87789 |
The ID of the snapshot template.
|
UserData | String | No | {"MessageCallback":{"CallbackURL":"http://test.test.com"},"Extend":{"localId":"xxx","test":"www"}} |
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.
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
RequestId | String | 25818875-5F78-4A*****F6-D7393642CA58 |
The ID of the request. |
SnapshotJob | Struct |
The information about the snapshot job. |
|
JobId | String | ad90a501b1b94b*****72374ad005046 |
The ID of the snapshot job. |
Examples
Sample requests
https://vod.{ApiRegion}.aliyuncs.com/?Action=SubmitSnapshotJob
&VideoId=d3e680e618708*****efbf2cae7cc931
&<Common request parameters>
Sample success responses
XML
format
<SubmitSnapshotJobResponse>
<RequestId>25818875-5F78-4A*****F6-D7393642CA58</RequestId>
<SnapshotJob>
<JobId>ad90a501b1b94b*****72374ad005046</JobId>
</SnapshotJob>
</SubmitSnapshotJobResponse>
JSON
format
{
"RequestId": "25818875-5F78-4A*****F6-D7393642CA58",
"SnapshotJob": {
"JobId": "ad90a501b1b94b*****72374ad005046"
}
}
Error codes
For a list of error codes, visit the API Error Center.
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. |
SDK examples
We recommend that you use a server SDK to call this operation. For more information about the sample code that is used to call this operation in various languages, see the following topics: