您可以通過視頻截幀功能,按一定規則提取多個視訊框架並轉換為需要的圖片格式。本文介紹視頻截幀功能參數及樣本。
功能簡介
視頻截幀是指從視頻中提取特定幀映像的過程,其目的是將視頻中某一特定時刻的畫面儲存為靜態圖片。

使用情境
快照:將視頻中的特定時刻儲存為靜態映像,以此製作海報。
分析:提取主要畫面格以便進行後續分析,例如Face Service、物體檢測等。
封面製作:為視頻建立縮圖或封面圖。
播放總結:從視頻中篩選多個關鍵時刻,以產生簡潔的總結或預覽。
截圖分享與記錄:使用者在觀看視頻時,如果遇到喜歡的畫面希望進行儲存或分享,可以通過截取該時刻的視訊框架來實現。
如何使用
前提條件
視頻截幀
僅支援使用Java、Python、Go SDK通過非同步處理的方式完成視頻截幀。
在填寫視頻截幀輸出檔案儲存路徑時,若未指定尾碼名(例如“.jpg”),系統將自動添加序號(例如“_0_1.jpg”)。如果已指定尾碼名,則系統僅會保留最後一張截圖,因此不建議使用此方式。如需自訂序號,可以通過ApsaraVideo for Media Processing相關變數進行設定。
Java
要求使用3.17.4及以上版本的Java SDK。
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 {
// yourEndpoint填寫Bucket所在地區對應的Endpoint。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 指定阿里雲通用Region ID,例如cn-hangzhou。
String region = "cn-hangzhou";
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 指定Bucket名稱,例如examplebucket。
String bucketName = "examplebucket";
// 指定按視頻截幀處理後的檔案名稱。
String targetKey = "dest.png";
// 指定原視頻檔案名稱。
String sourceKey = "src.mp4";
// 建立OSSClient執行個體。
// 當OSSClient執行個體不再使用時,調用shutdown方法以釋放資源。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 構建視頻處理樣式字串以及視頻截幀處理參數。
String style = String.format("video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000");
// 構建非同步處理指示。
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);
// 建立AsyncProcessObjectRequest對象。
AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
// 執行非同步處理任務。
AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
System.out.println("EventId: " + response.getEventId());
System.out.println("RequestId: " + response.getRequestId());
System.out.println("TaskId: " + response.getTaskId());
} finally {
// 關閉OSSClient。
ossClient.shutdown();
}
}
}Python
要求使用Python SDK 2.18.4及以上版本。
# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
def main():
# 從環境變數中擷取臨時訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# 指定阿里雲通用Region ID,例如cn-hangzhou。
region = 'cn-hangzhou'
# 填寫Bucket名稱,例如examplebucket。
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
# 指定原視頻檔案名稱。
source_key = 'src.mp4'
# 指定按視頻截幀處理後的檔案名稱。
target_key = 'dest.png'
# 構建視頻截幀參數。
animation_style = 'video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000'
# 構建處理指示,包括儲存路徑和Base64編碼的Bucket名和目標檔案名。
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:
# 執行非同步處理任務。
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
要求使用Go SDK 3.0.2及以上版本。
package main
import (
"encoding/base64"
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
"log"
)
func main() {
// 從環境變數中擷取臨時訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 建立OSSClient執行個體。
// yourEndpoint填寫Bucket對應的Endpoint,以華東1(杭州)為例,填寫為https://oss-cn-hangzhou.aliyuncs.com。其他Region請按實際情況填寫。
// yourRegion指定阿里雲通用Region ID,例如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)
}
// 指定Bucket名稱,例如examplebucket。
bucketName := "examplebucket"
bucket, err := client.Bucket(bucketName)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 指定原視頻檔案名稱。
sourceKey := "src.mp4"
// 指定按視頻截幀處理後的檔案名稱。
targetKey := "dest.png"
// 構建視頻截幀參數。
animationStyle := "video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000"
// 構建處理指示,包括儲存路徑和Base64編碼的Bucket名稱和目標檔案名稱。
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)
// 執行非同步處理任務。
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)
}參數說明
操作名稱:video/snapshots
具體參數如下表所示。
參數 | 類型 | 是否必須 | 描述 |
ss | int | 否 | 視頻截幀的起始時間,單位為毫秒。取值:
|
f | string | 是 | 圖片輸出格式,取值:
|
m | string | 否 | 截幀模式,預設為inter,取值:
|
thr | int | 否 | dhash 模式截幀閾值,閾值越大截幀數量越少,取值範圍為[0,100],預設值為 0。 說明 僅在使用 dhash 模式時有效。 dhash 模式對閾值較為敏感,推薦該參數設定不大於 25,並根據具體情境調整。 |
num | int | 否 | 截幀數量,預設為0,表示不限制截幀數量。預設值對於不同截幀模式的物理意義如下:
重要 受視頻長度與截幀參數影響,實際截幀數量可能會小於設定的參數值。 |
inter | int | 否 | 截幀間隔,單位為毫秒,預設為0,表示截取所有視訊框架。 說明 當該參數小於源視訊框架間隔(幀率倒數)時,會按源視訊框架間隔進行截幀。 |
w | int | 否 | 輸出圖片的寬度,單位為px,取值範圍為[32,4096],預設與源視頻寬度相同。 |
h | int | 否 | 輸出圖片的高度,單位為px,取值範圍為[32,4096],預設與源視頻高度相同。 |
pw | int | 否 | 輸出圖片寬度與原始視頻寬度的百分比,取值範圍為(0,200],預設值為100。 說明 當w與pw同時設定時,pw無效。 |
ph | int | 否 | 輸出圖片高度與原始視頻高度的百分比,取值範圍為(0,200],預設值為100。 說明 當h與ph同時設定時,ph無效。 |
scaletype | string | 否 | 縮放方式。取值:
|
相關API
以上操作方式底層基於API實現,如果您的程式自訂要求較高,您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。關於公用要求標頭Authorization的計算方法,請參見簽名版本4(推薦)。
在使用API調用前,需要您綁定IMM專案,請參見AttachOSSBucket - 綁定Object Storage Service桶。
每10秒截1幀圖片用於AI模型訓練或推理
每10秒截取一幀映像,用於AI模型的訓練或推理,輸出映像的解析度限制為512x512。
截幀資訊
源檔案
視頻名稱:example.mkv
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截框架格式:jpg
視頻間隔:10s
輸出圖片解析度:512x512
縮放方式:縮放並裁剪
檔案儲存體路徑
jpg檔案:oss://outbucket/outobjprefix-%d.jpg
處理樣本
// 對檔案example.mkv進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK每隔4秒截1幀,共截5幀用於分析視頻片段
從第11秒開始,每隔4秒截取1幀,共截取5幀用於分析視頻片段。輸出的圖片寬高為視頻解析度的1/2,並儲存為PNG格式圖片。
截幀資訊
源檔案
視頻名稱:example.mkv
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截框架格式:png
起始時間:11s
視頻間隔:4s
截幀數量:5
輸出圖片解析度:寬高都為源視頻的一半
檔案儲存體路徑
png檔案:oss://outbucket/outobjprefix-%d.png
處理樣本
// 對檔案example.mkv進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK截取視頻中的事件主要畫面格
通過dhash分析視訊框架的內容相似性,並配合閾值提取映像內容變化較大的幀作為事件主要畫面格。
閾值參數(thr)需根據具體業務情境進行調整。
截幀資訊
源檔案
視頻名稱:example.mkv
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截幀模式:dhash
截框架格式:jpg
閾值:15
視頻間隔:1s
輸出圖片解析度:與原視頻一致
檔案儲存體路徑
jpg檔案:oss://outbucket/outobjprefix-%d.jpg
處理樣本
// 對檔案example.mkv進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK截取視頻中最具代表性的5個事件主要畫面格,用於推理
通過dhash分析視訊框架的內容相似性,並截取映像內容變化最顯著的5幀。
截幀資訊
源檔案
視頻名稱:example.mkv
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截幀模式:dhash
截框架格式:jpg
截幀數量:5
視頻間隔:1s
輸出圖片解析度:與原視頻一致
檔案儲存體路徑
jpg檔案:oss://outbucket/outobjprefix-%d.jpg
處理樣本
// 對檔案example.mkv進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK截取視頻中的所有IDR幀
截幀資訊
源檔案
視頻名稱:example.mkv
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截幀模式:key
截框架格式:jpg
輸出圖片解析度:與原視頻一致
檔案儲存體路徑
jpg檔案:oss://outbucket/outobjprefix-%d.jpg
處理樣本
// 對檔案example.mkv進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK以均勻時間間隔截取10幀
截幀資訊
源檔案
視頻名稱:example.mkv
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截幀模式:avg
截框架格式:jpg
截幀數量:10
輸出圖片解析度:與原視頻一致
檔案儲存體路徑
jpg檔案:oss://outbucket/outobjprefix-%d.jpg
處理樣本
// 對檔案example.mkv進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK截取音頻封面
一些音頻檔案包含歌曲或專輯封面,使用視頻截幀能力進行提取。
截幀資訊
源檔案
視頻名稱:example.flac
訊息通知
訊息通知MNS主題:example-mns-topic
輸出配置
截幀資訊
截框架格式:jpg
輸出圖片解析度:與原視頻一致
檔案儲存體路徑
jpg檔案:oss://outbucket/cover.jpg
處理樣本
// 對檔案example.flac進行視頻截幀。
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_ZXhhbXBsZS1tbnMtdG9waWMK計費說明
在視頻截幀過程中,由於調用了 IMM 服務, OSS 和 IMM 兩側會產生以下計費項目:
OSS 側: 詳細定價請參見OSS產品定價
API
計費項目
說明
GetObject
GET 類型請求
根據成功的請求次數計算請求費用。
外網流出流量費用
如果是通過外網Endpoint(樣本值oss-cn-hangzhou.aliyuncs.com)或者傳輸加速Endpoint(樣本值oss-accelerate.aliyuncs.com)調用GetObject介面時,會產生外網流出流量費用,根據資料容量大小計費。
低頻訪問資料取回容量
如果取回的資料是低頻訪問資料,會產生低頻訪問資料取回容量的費用,按資料取回量計費。
歸檔直讀資料取回容量
如果讀取的是歸檔的Object且Bucket開啟了歸檔直讀,會產生歸檔直讀資料取回容量費用,根據取回的資料容量大小計費。
傳輸加速
如果開啟了傳輸加速功能且使用傳輸加速網域名稱訪問您的Bucket會產生傳輸加速費用,根據資料容量大小計費。
PutObject
PUT類型請求
根據成功的請求次數計算請求費用。
儲存費用
根據Object的儲存類型、大小和時間長度收取儲存費用。
HeadObject
GET 類型請求
根據成功的請求次數計算請求費用。
IMM 側: 詳細定價請參見IMM計費項目
重要自北京時間 2025 年 7 月 28 日 11:00 起,IMM 視頻截幀服務正式降價,具體的計費項目為VideoFraming,更多資訊請參見IMM計費調整公告。
API
計費項目
說明
CreateMediaConvertTask
VideoFraming
根據成功的截幀數量計算視頻截幀的費用。
注意事項
視頻截幀僅支援非同步處理(x-oss-async-process處理方式)。
視頻截幀可能由於視頻時間戳記或碼流的損壞而失敗或產生的圖片檔案數量不正確。
不支援匿名訪問。
常見問題
視頻截幀功能支援過濾掉黑屏嗎?
不支援。
視頻截幀功能支援產生視頻縮減短視頻嗎?
不支援,可考慮使用視頻轉動圖功能,詳細資料請參見視頻轉動圖。
視頻截幀對視頻格式有限制嗎?
支援所有主流視頻格式,無任何限制。
在fast mode下,視頻截幀功能如果截取的幀時間位於第一秒,那麼實際截取的幀將接近於第一秒之前的最近主要畫面格嗎?
是的。
客戶上傳的視頻想顯示其中某一幀作為封面,但是顯示的是一張灰圖?
當視頻碼率過高時,視頻截幀可能會出現灰圖現象。為避免此情況,可以提前對視頻進行轉碼處理。