最近更新时间:2026-11-18 14:05:03
操作名称:video/snapshot
当您需要获取视频封面、提取视频关键帧图像进行视频编辑,或者提取视频中特定场景帧图像用于视频监控时,可以将视频上传至KS3存储空间,通过视频截帧提取关键帧图片,实时截取视频中的单帧图像并返回。
使用该功能的客户必须具有源桶的ks3:GetObject。如果需要另存为(持久化)功能,还需要具有源桶的ks3:PostProcessTask权限,目标桶的ks3:PutObject权限。
视频封面:提取视频首帧或指定时间点作为视频封面展示。
关键帧提取:获取视频中特定时间点的画面用于内容分析。
视频监控:从监控视频中截取特定时刻的画面存档。
缩略图生成:按指定尺寸生成视频缩略图。
方式一:GET请求头发送请求
GET /{ObjectKey}?x-kss-process=video/snapshot,{params} HTTP/1.1
Host: {BucketName}.{endpoint}
Authorization: {SignatureValue}方式二:URL携带参数请求
https://bucketname.ks3-cn-beijing.ksyuncs.com/objectname.mp4?x-kss-process=video/snapshot,{params}&<Auth String>方式三:POST请求
POST /{ObjectKey}?x-kss-process HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {Content-Length}
Date: {date}
x-kss-storage-class: {StorageClass}
Authorization: {SignatureValue}
x-kss-process=video/snapshot,{params}|sys/saveas,o_,b_(转存操作)参数名称 | 描述 | 是否必选 |
|---|---|---|
x-kss-process | 操作类型,固定取值: video/snapshot。
| 是 |
t | 指定截图时间,单位为毫秒。
1. 如果需要截取视频封面(通常为首帧或关键帧),则t设置为0。 2. 如果取值超过了视频时长,则返回视频的最后一个关键帧。 | 是 |
w | 指定截图宽度,单位为像素(px)。
1. 如果指定为0,则根据截图高度与源视频高度比例自动计算宽度。 2. 如果宽度和高度都设置为0,则输出为原视频宽高。 | 否 |
h | 截图的高,单位为像素(px)
1. 如果指定为0,则根据截图宽度与源视频宽度比例自动计算高度。 2. 如果宽度和高度都设置为0,则输出为原视频宽高。 | 否 |
m | 指定截图模式,不指定则默认根据时间精确截图。如果指定为fast,则截取该时间点之前的最近的一个关键帧。
1. 精确模式(默认):会解码到指定时间点,精确度最高,但处理时间稍长。 2. 快速模式(m_fast):直接取最近的关键帧,处理速度快,但时间点可能略早。 | 否 |
f | 截图的格式。
| 否 |
ar | 指定是否根据视频信息自动旋转图片。 取值说明如下:
| 否 |
该接口仅使用公共请求头。
仅POST请求时支持传入请求体。
该接口仅返回公共响应头。
响应体为截图文件内容。
示例1:截取视频首帧,输出原尺寸JPG格式。
GET /sample.mp4?x-kss-process=video/snapshot,t_0,f_jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string示例2:截取视频第7秒(7000 毫秒)的画面。
GET /sample.mp4?x-kss-process=video/snapshot,t_7000 HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string示例3:截取视频封面,生成宽度为800像素的缩略图(高度自动按比例计算)。
GET /sample.mp4?x-kss-process=video/snapshot,t_0,w_800 HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string示例4:截取第10秒画面,输出800×600像素的PNG图片,使用快速模式。
GET /sample.mp4?x-kss-process=video/snapshot,t_10000,f_png,w_800,h_600,m_fast HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string示例5:截取第10秒画面,输出PNG图片,另存到mybucket中,Key为output/sample.mp4。
POST /sample.mp4?x-kss-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Content-Length: {Content-Length}
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-kss-storage-class: STANDARD
Authorization: {SignatureValue}
x-kss-process=video/snapshot,t_10000,f_png|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L3NhbXBsZS5tcDQ=返回截取的图片二进制数据。
HTTP状态码 | 错误码 | 描述 |
|---|---|---|
404 Not Found | NoSuchBucket | 指定的存储桶不存在。 |
404 Not Found | NoSuchKey | 指定的视频对象文件不存在。 |
403 Forbidden | AccessDenied | 权限不足。 |
400 Bad Request | InvalidRequest | 存在以下情况:
|
400 Bad Request | InvalidArgument | 参数异常,包括必选参数缺失、参数类型错误、参数值为空等场景。 |
400 Bad Request | MediaParseFailed | 存在以下情况:
|
视频截帧当前邀测期间暂不收费,邀测结束后开始根据截帧数量收费。
纯净模式
