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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

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:

  • CoverSnapshot: thumbnail snapshot
  • NormalSnapshot: normal snapshot
  • SpriteSnapshot: sprite snapshot
  • SpriteOriginSnapshot: sprite source snapshot
  • WebVttSnapshot: WebVTT snapshot
AuthTimeout String No 3600

The validity period of the snapshot URL. Unit: seconds. Default value: 3600. Minimum value: 3600.

  • This parameter only takes effect when URL authentication is enabled.
  • If the specified validity period is less than 3600 seconds, the default value is 3600.
  • If an Object Storage Service (OSS) URL is returned, the maximum validity period is limited to 2592000 seconds (30 days) to reduce security risks of the origin.
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: