Queries the snapshots that are captured from the specified media.
Usage note
If multiple snapshots of a video exist, the data of the latest snapshot is returned.
QPS limit
A single user can perform a maximum of 30 queries per second (QPS). Throttling is triggered when the number of calls per second exceeds the QPS limit. The throttling may affect your business. Thus, we recommend that you observe the QPS limit on this operation.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | ListSnapshots |
The operation that you want to perform. Set the value to ListSnapshots. |
VideoId | String | Yes | d3e680e618708*****fbf2cae7cc931 |
The ID of the video. |
SnapshotType | String | No | CoverSnapshot |
The type of snapshots that are returned. Valid values:
|
AuthTimeout | String | No | 3600 |
The validity period of the snapshot URL. Unit: seconds. Default value: 3600. Minimum value: 3600.
|
PageSize | String | No | 20 |
The number of entries to return on each page. Default value: 20. Maximum value: 100. |
PageNo | String | No | 1 |
The number of the page to turn. Default value: 1. |
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
MediaSnapshot | Struct |
The snapshot data of the media. |
|
CreationTime | String | 2017-12-20T12:23:45Z |
The time when the snapshot job was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC. |
JobId | String | ad90a501b1b9472374ad005046**** |
The ID of the snapshot job. |
Regular | String | http://example.aliyundoc.com/snapshot/sample{SnapshotCount}.jpg |
The rule for generating snapshot URLs. |
Snapshots | Array of Snapshot |
The snapshot data. |
|
Snapshot | |||
Index | Long | 1 |
The index of the snapshot. |
Url | String | http://example.aliyundoc.com/snapshot/sample00001****.jpg |
The URL of the snapshot. |
Total | Long | 100 |
The total number of snapshots. |
RequestId | String | 25818875-5F78-4AF6-D7393642CA58**** |
The ID of the request. |
Examples
Sample requests
http(s)://vod.cn-shanghai.aliyuncs.com/?Action=ListSnapshots
&VideoId=d3e680e618708fbf2cae7cc931****
&SnapshotType=CoverSnapshot
&AuthTimeout=3600
&PageSize=20
&PageNo=1
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<ListSnapshotsResponse>
<RequestId>25818875-5F78-4AF6-D7393642CA58****</RequestId>
<MediaSnapshot>
<CreationTime>2017-12-20T12:23:45Z</CreationTime>
<Regular>http://example.aliyundoc.com/snapshot/sample{SnapshotCount}.jpg</Regular>
<Total>100</Total>
<JobId>ad90a501b1b9472374ad005046****</JobId>
<Snapshots>
<Index>1</Index>
<Url>http://example.aliyundoc.com/snapshot/sample00001****.jpg</Url>
</Snapshots>
</MediaSnapshot>
</ListSnapshotsResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "25818875-5F78-4AF6-D7393642CA58****",
"MediaSnapshot" : {
"CreationTime" : "2017-12-20T12:23:45Z",
"Regular" : "http://example.aliyundoc.com/snapshot/sample{SnapshotCount}.jpg",
"Total" : 100,
"JobId" : "ad90a501b1b9472374ad005046****",
"Snapshots" : [ {
"Index" : 1,
"Url" : "http://example.aliyundoc.com/snapshot/sample00001****.jpg"
} ]
}
}
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 query the snapshot data of videos only when they are 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: