SubmitSnapshotJob - ApsaraVideo VOD - Alibaba Cloud Documentation Center

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

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

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:
- For mandatory resource types, indicate with a prefix of * .
- 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.

Operation	Access level	Resource type	Condition key	Associated operation
vod:SubmitSnapshotJob	create	All Resources ``	none	none

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: 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.	d3e680e618708efbf2cae7cc9312****
SpecifiedOffsetTime	long	No	The point in time when the first snapshot is captured. Unit: milliseconds. Default value: 0.	0
Width	string	No	The width of each snapshot. Valid values: `[8,4096]`. By default, the width of the video source is used. Unit: pixels.	1280
Height	string	No	The height of each snapshot. Valid values: `[8,4096]`. By default, the height of the video source is used. Unit: pixels.	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. 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.	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. 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.	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

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

Parameter	Type	Description	Example
	object	The returned results.
RequestId	string	The ID of the request.	25818875-5F78-5EB0-4AF6-D7393642****
SnapshotJob	object	The information about the snapshot job.
JobId	string	The ID of the snapshot job.	ad90a501b1b94b72374ad0050464****

Examples

Sample success responses

JSONformat

{
  "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.