全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

视频截帧

最近更新时间:2026-11-18 14:05:03

操作名称:video/snapshot

  • 当您需要获取视频封面、提取视频关键帧图像进行视频编辑,或者提取视频中特定场景帧图像用于视频监控时,可以将视频上传至KS3存储空间,通过视频截帧提取关键帧图片,实时截取视频中的单帧图像并返回。

  • 使用该功能的客户必须具有源桶的ks3:GetObject。如果需要另存为(持久化)功能,还需要具有源桶的ks3:PostProcessTask权限,目标桶的ks3:PutObject权限。

1. 单个UID QPS建议不超50,如有更大需求,请联系商务或提交工单申请。

2. 当前仅支持北京区域。

3. 源文件大小建议不超25GB,视频时长建议不超5小时。

使用场景

  • 视频封面:提取视频首帧或指定时间点作为视频封面展示。

  • 关键帧提取:获取视频中特定时间点的画面用于内容分析。

  • 视频监控:从监控视频中截取特定时刻的画面存档。

  • 缩略图生成:按指定尺寸生成视频缩略图。

请求

请求格式

  • 方式一: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。

  • 类型:String

是

t

指定截图时间,单位为毫秒。

  • 类型:Int

  • 取值范围:[0,视频时长]

1. 如果需要截取视频封面(通常为首帧或关键帧),则t设置为0。

2. 如果取值超过了视频时长,则返回视频的最后一个关键帧。

是

w

指定截图宽度,单位为像素(px)。

  • 类型:Int

  • 取值范围: [0, 视频宽度]

  • 默认值:0

1. 如果指定为0,则根据截图高度与源视频高度比例自动计算宽度。

2. 如果宽度和高度都设置为0,则输出为原视频宽高。

否

h

截图的高,单位为像素(px)

  • 类型:Int

  • 取值范围: [0, 视频高度]

  • 默认值:0

1. 如果指定为0,则根据截图宽度与源视频宽度比例自动计算高度。

2. 如果宽度和高度都设置为0,则输出为原视频宽高。

否

m

指定截图模式,不指定则默认根据时间精确截图。如果指定为fast,则截取该时间点之前的最近的一个关键帧。

  • 类型:String

1. 精确模式(默认):会解码到指定时间点,精确度最高,但处理时间稍长。

2. 快速模式(m_fast):直接取最近的关键帧,处理速度快,但时间点可能略早。

否

f

截图的格式。

  • 类型:String

  • 取值:jpg(默认)、png

否

ar

指定是否根据视频信息自动旋转图片。

取值说明如下:

  • auto:指定在截图生成之后根据视频信息进行自动旋转。

  • h:指定在截图生成之后根据视频信息强制按高大于宽的模式旋转。

  • w:指定在截图生成之后根据视频信息强制按宽大于高的模式旋转。

否

请求头

该接口仅使用公共请求头。

请求体

仅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

存在以下情况:

  • 请求不合法,包括URL 格式错误、请求协议异常等。

  • 请求 URL 中重复填写同一请求参数。

400 Bad Request

InvalidArgument

参数异常,包括必选参数缺失、参数类型错误、参数值为空等场景。

400 Bad Request

MediaParseFailed

存在以下情况:

  • 文件为未完成解冻的归档、冷归档存储类型。开启归档直读后将不受影响。

  • 源文件大小超出限制,最大支持 50GB。

  • 视频时长超出限制,最大支持 10小时。

  • 媒体编码格式不在服务支持范围内。

  • 媒体容器格式不在服务支持范围内。

  • 视频文件损坏,解码失败,无法截取画面等。

费用

视频截帧当前邀测期间暂不收费,邀测结束后开始根据截帧数量收费。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈