You can use the video snapshot feature to extract multiple video frames based on specific rules and convert them to your desired image format. This topic describes the parameters and provides examples for the video snapshot feature.
Feature introduction
Frame capture refers to the process of extracting specific frame images from a video to save specific moments in the video as static images.
Scenarios
Snapshot: Save a specific moment in a video as a static image to create a poster.
Analysis: Extract keyframes for subsequent analysis, such as facial recognition and object detection.
Thumbnail creation: Create thumbnails or cover images for videos.
Playback summary: Select multiple key moments from a video to generate a concise summary or preview.
Screenshot sharing and recording: When users watch videos and want to save or share a frame they like, they can capture the video frame at that moment.
How to use this feature
Prerequisites
In OSS, create a bucket and upload the files that you want to process to the bucket.
Create an IMM project and attach it. You can attach the project in the OSS console or by calling an API. The project must be in the same region as the bucket.
You have granted operation permissions for an authorized user.
Capture video frames
You can capture video frames only asynchronously using the Java, Python, or Go SDK.
If you do not specify a suffix, such as .jpg, for the storage path of captured frames, the system automatically adds a serial number, such as _0_1.jpg. If you specify a suffix, only the last captured frame is retained. We recommend that you do not specify a suffix. To customize the serial number, you can use ApsaraVideo Media Processing variables.
Java
You must use Java SDK 3.17.4 or later.
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AsyncProcessObjectRequest;
import com.aliyun.oss.model.AsyncProcessObjectResult;
import com.aliyuncs.exceptions.ClientException;
import java.util.Base64;
public class Demo {
public static void main(String[] args) throws ClientException {
// Replace yourEndpoint with the Endpoint of the region where the bucket is located.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Specify a general-purpose Alibaba Cloud region ID, such as cn-hangzhou.
String region = "cn-hangzhou";
// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the name of the file after it is processed by video snapshot.
String targetKey = "dest.png";
// Specify the name of the source video file.
String sourceKey = "src.mp4";
// Create an OSSClient instance.
// When the OSSClient instance is no longer used, call the shutdown method to release resources.
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// Build the video processing style string and video snapshot parameters.
String style = String.format("video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000");
// Build the asynchronous processing instruction.
String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetKey.getBytes());
String process = String.format("%s|sys/saveas,b_%s,o_%s/notify,topic_QXVkaW9Db252ZXJ0", style, bucketEncoded, targetEncoded);
// Create an AsyncProcessObjectRequest object.
AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
// Execute the asynchronous processing task.
AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
System.out.println("EventId: " + response.getEventId());
System.out.println("RequestId: " + response.getRequestId());
System.out.println("TaskId: " + response.getTaskId());
} finally {
// Shut down the OSSClient.
ossClient.shutdown();
}
}
}Python
You must use Python SDK 2.18.4 or later.
# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
def main():
# Obtain temporary access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the Endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# Specify a general-purpose Alibaba Cloud region ID, such as cn-hangzhou.
region = 'cn-hangzhou'
# Specify the bucket name, for example, examplebucket.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
# Specify the name of the source video file.
source_key = 'src.mp4'
# Specify the name of the file after it is processed by video snapshot.
target_key = 'dest.png'
# Build the video snapshot parameters.
animation_style = 'video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000'
# Build the processing instruction, including the save path and the Base64-encoded bucket name and object file name.
bucket_name_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
target_key_encoded = base64.urlsafe_b64encode(target_key.encode()).decode().rstrip('=')
process = f"{animation_style}|sys/saveas,b_{bucket_name_encoded},o_{target_key_encoded}/notify,topic_QXVkaW9Db252ZXJ0"
try:
# Execute the asynchronous processing task.
result = bucket.async_process_object(source_key, process)
print(f"EventId: {result.event_id}")
print(f"RequestId: {result.request_id}")
print(f"TaskId: {result.task_id}")
except Exception as e:
print(f"Error: {e}")
if __name__ == "__main__":
main()Go
You must use Go SDK 3.0.2 or later.
package main
import (
"encoding/base64"
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
"log"
)
func main() {
// Obtain temporary access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Create an OSSClient instance.
// Replace yourEndpoint with the Endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, specify the actual Endpoint.
// Replace yourRegion with a general-purpose Alibaba Cloud region ID, such as cn-hangzhou.
client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Specify the bucket name, for example, examplebucket.
bucketName := "examplebucket"
bucket, err := client.Bucket(bucketName)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Specify the name of the source video file.
sourceKey := "src.mp4"
// Specify the name of the file after it is processed by video snapshot.
targetKey := "dest.png"
// Build the video snapshot parameters.
animationStyle := "video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000"
// Build the processing instruction, including the save path and the Base64-encoded bucket name and object file name.
bucketNameEncoded := base64.URLEncoding.EncodeToString([]byte(bucketName))
targetKeyEncoded := base64.URLEncoding.EncodeToString([]byte(targetKey))
process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v/notify,topic_QXVkaW9Db252ZXJ0", animationStyle, bucketNameEncoded, targetKeyEncoded)
// Execute the asynchronous processing task.
result, err := bucket.AsyncProcessObject(sourceKey, process)
if err != nil {
log.Fatalf("Failed to async process object: %s", err)
}
fmt.Printf("EventId: %s\n", result.EventId)
fmt.Printf("RequestId: %s\n", result.RequestId)
fmt.Printf("TaskId: %s\n", result.TaskId)
}Parameters
Action: video/snapshots
The following table describes the parameters.
Parameter | Type | Required | Description |
ss | int | No | The start time for the video snapshot, in milliseconds. Valid values:
|
f | string | Yes | The output format of the image. Valid values:
|
m | string | No | The snapshot mode. The default value is inter. Valid values:
|
thr | int | No | The snapshot threshold for the dhash mode. A larger threshold results in fewer snapshots. The value ranges from 0 to 100. The default value is 0. Note This parameter is valid only in dhash mode. The dhash mode is sensitive to the threshold. Set this parameter to a value no greater than 25 and adjust it as needed. |
num | int | No | The number of snapshots. The default value is 0, which means no limit on the number of snapshots. The physical meaning of the default value varies by snapshot mode:
Important The actual number of snapshots may be less than the specified value due to the video length and snapshot parameters. |
inter | int | No | The snapshot interval, in milliseconds. The default value is 0, which means all video frames are captured. Note If this value is less than the source video keyframe interval (the reciprocal of the frame rate), snapshots are captured at the source video keyframe interval. |
w | int | No | The width of the output image, in pixels. The value must be between 32 and 4096. By default, the width is the same as the source video. |
h | int | No | The height of the output image, in pixels. The value must be between 32 and 4096. By default, the height is the same as the source video. |
pw | int | No | The percentage of the output image width relative to the source video width. The value must be between 0 and 200. The default value is 100. Note If both w and pw are set, pw is invalid. |
ph | int | No | The percentage of the output image height relative to the source video height. The value must be between 0 and 200. The default value is 100. Note If both h and ph are set, ph is invalid. |
scaletype | string | No | The scaling method. Valid values:
|
The sys/saveas and notify parameters are also used for video snapshots. For more information, see Save as and Notifications.
Related API operations
If your application requires a high level of customization, you can directly call RESTful APIs. In this case, you must write code to calculate the signature. For information about how to calculate the signature for the Authorization common request header, see Signature Version 4 (Recommended).
Before you make API calls, you must attach an IMM project. For more information, see AttachOSSBucket - Attach an Object Storage bucket.
Capture one frame every 10 seconds for AI model training or inference
Capture one frame every 10 seconds for AI model training or inference. The output image resolution is limited to 512 × 512.
Snapshot information
Source file
Video name: example.mkv
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot format: jpg
Video interval: 10 s
Output image resolution: 512 × 512
Scaling method: Scale and crop
File storage path
JPG file: oss://outbucket/outobjprefix-%d.jpg
Processing example
// Capture snapshots of the example.mkv file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,f_jpg,w_512,h_512,scaletype_crop,inter_10000|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKCapture one frame every 4 seconds for a total of 5 frames to analyze a video segment
Starting from the 11th second, capture one frame every 4 seconds for a total of 5 frames to analyze a video segment. The width and height of the output image are half of the source video resolution. The image is saved in PNG format.
Snapshot information
Source file
Video name: example.mkv
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot format: png
Start time: 11 s
Video interval: 4 s
Number of snapshots: 5
Output image resolution: Half the width and height of the source video
File storage path
PNG file: oss://outbucket/outobjprefix-%d.png
Processing example
// Capture snapshots of the example.mkv file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,ss_11000,f_png,pw_50,ph_50,num_5|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKCapture event keyframes from a video
Use dhash to analyze the content similarity of video frames and extract frames with significant content changes as event keyframes based on a specified threshold.
The threshold parameter (thr) must be adjusted based on your business scenario.
Snapshot information
Source file
Video name: example.mkv
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot mode: dhash
Snapshot format: jpg
Threshold: 15
Video interval: 1 s
Output image resolution: Same as the source video
File storage path
JPG file: oss://outbucket/outobjprefix-%d.jpg
Processing example
// Capture snapshots of the example.mkv file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,m_dhash,f_jpg,inter_1000,thr_15|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKCapture the 5 most representative event keyframes from a video for inference
Use dhash to analyze the content similarity of video frames and capture the 5 frames with the most significant image content changes.
Snapshot information
Source file
Video name: example.mkv
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot mode: dhash
Snapshot format: jpg
Number of snapshots: 5
Video interval: 1 s
Output image resolution: Same as the source video
File storage path
JPG file: oss://outbucket/outobjprefix-%d.jpg
Processing example
// Capture snapshots of the example.mkv file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,m_dhash,f_jpg,inter_1000,num_5|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKCapture all IDR frames from a video
Snapshot information
Source file
Video name: example.mkv
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot mode: key
Snapshot format: jpg
Output image resolution: Same as the source video
File storage path
JPG file: oss://outbucket/outobjprefix-%d.jpg
Processing example
// Capture snapshots of the example.mkv file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,m_key,f_jpg|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKCapture 10 frames at even intervals
Snapshot information
Source file
Video name: example.mkv
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot mode: avg
Snapshot format: jpg
Number of snapshots: 10
Output image resolution: Same as the source video
File storage path
JPG file: oss://outbucket/outobjprefix-%d.jpg
Processing example
// Capture snapshots of the example.mkv file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,m_avg,f_jpg,num_10|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKExtract an audio cover
Some audio files contain song or album covers. You can use the video snapshot feature to extract them.
Snapshot information
Source file
Video name: example.flac
Notification
MNS topic for notifications: example-mns-topic
Output configuration
Snapshot information
Snapshot format: jpg
Output image resolution: Same as the source video
File storage path
JPG file: oss://outbucket/cover.jpg
Processing example
// Capture snapshots of the example.flac file.
POST /example.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-async-process=video/snapshots,f_jpg|sys/saveas,b_b3V0YnVja2V0,o_Y292ZXIuanBnCg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMKBilling
The video snapshot process generates billable items for both OSS and IMM because it uses the IMM service:
OSS: For more information about pricing, see OSS Pricing
API
Billable item
Description
GetObject
GET requests
Request fees are calculated based on the number of successful requests.
Outbound traffic over the internet
If you call the GetObject operation using a public Endpoint (for example, oss-cn-hangzhou.aliyuncs.com) or an acceleration endpoint (for example, oss-accelerate.aliyuncs.com), fees for outbound traffic over the internet are generated. These fees are charged based on the data volume.
Volume of retrieved Infrequent Access data
If the retrieved data is Infrequent Access (IA) data, fees are generated for the volume of retrieved IA data. These fees are charged based on the volume of retrieved data.
Volume of retrieved data using real-time access of Archive objects
If you read an Archive object and real-time access of Archive objects is enabled for the bucket, fees are generated for the volume of retrieved data. These fees are charged based on the volume of retrieved data.
Transfer acceleration
If transfer acceleration is enabled and you use an acceleration endpoint to access your bucket, transfer acceleration fees are generated. These fees are charged based on the data volume.
PutObject
PUT requests
Request fees are calculated based on the number of successful requests.
Storage fees
Storage fees are charged based on the storage class, size, and duration of the object.
HeadObject
GET requests
Request fees are calculated based on the number of successful requests.
IMM: For more information about pricing, see IMM billable items
ImportantStarting from 11:00 (UTC+8) on July 28, 2025, the price of the IMM video snapshot service will be reduced. The specific billable item is VideoFraming. For more information, see IMM Billing Adjustment Announcement.
API
Billable item
Description
CreateMediaConvertTask
VideoFraming
Video snapshot fees are calculated based on the number of successful snapshots.
Notes
Video snapshot supports only asynchronous processing (the x-oss-async-process method).
Video snapshot may fail or generate an incorrect number of image files due to video timestamp or stream corruption.
Anonymous access will be denied.
FAQ
Does the video snapshot feature support filtering out black screens?
No, it does not.
Does the video snapshot feature support generating short video thumbnails?
No, it does not. You can use the video-to-animated-image feature. For more information, see Convert videos to animated images.
Are there any restrictions on the video format for video snapshots?
No, there are not. All major video formats are supported without any restrictions.
In fast mode, if the snapshot time is within the first second, is the actual captured frame the nearest keyframe before the first second?
Yes, it is.
I want to display a specific frame of an uploaded video as a cover, but a gray image is displayed. Why?
If the video bitrate is too high, a gray image may appear during video snapshot. To avoid this, you can transcode the video in advance.