智能多媒体服务

    • 智能多媒体服务 > API 文档 > 音视频处理 >视频采样缩略图（vsample）

    视频采样缩略图（vsample）

    最近更新时间: 2025-04-08 15:57:54

    简介

    视频采样缩略图接口(vsample)用于从视频文件中截取多帧画面并按指定大小缩放成图片。

    参数说明

    vsample/<Format>
       /ss/<StartTime>
       /t/<Duration>
       /s/<Resolution>
       /rotate/<Degree>
       /interval/<Interval>
       /frames/<Frames>
       /savePattern/<savePattern>
    参数名称 必填 说明
    <Format> 是 输出的目标截图格式，支持jpg、png等。
    /ss/<StartTime> 指定截取视频的开始时刻，单位：秒,精度为 100ms，例如 /ss/1.1；默认从片头开始。
    /t/<Duration> 采样总时长，单位：秒,精度为 100ms，例如 t/1.1；默认表示到片尾结束。
    /s/<Resolution> 0. 指定截图分辨率，格式为宽 x 高 ，长边取值范围[20,3840]的整数，短边取值范围[20,2160]的整数。
    1. 宽、高都为空时，则和原视频保持一致
    2. 宽为空，高不为空，则按高的值对原视频等比例缩放
    3. 宽不为空，高为空时，则按宽的值对原视频等比例缩放
    4. 宽、高都不为空时，则根据宽、高来缩放
    /rotate/<Degree> 指定顺时针旋转的度数，可取值为90、180、270、auto。
    默认为不旋转。
    /interval/<Interval> 指定截帧间隔时间，单元：秒。
    默认为5秒,精度为 100ms，例如/interval/0.1指定平均截帧，截取的图片数量。 例如/frames/1。
    注意：
    1. 和 frames 参数不能同时设置。
    2. frames 和 interval 都不指定的情况，默认使用 interval。
    /frames/<Frames> 指定平均截帧，截取的图片数量。 例如/frames/10，截取10张图片。
    注意：
    1. 和 interval 参数不能同时设置。
    2. frames 和 interval 都不指定的情况，默认使用 interval。
    3. 当设置frames 值大于源视频帧数时，会按照源视频最大帧数来输出。
    4. 建议截帧帧率是视频帧率的整数倍。
    /savePattern/<savePattern> 是 指定各张截图的资源名格式，需要对设定值做URL安全的Base64编码。
    命名支持使用变量：
    1. 可以使用 $(变量名)或${变量名} 形式求值，魔法变量使用说明，参考 文件名变量 。
    2. 注意：$(count)为必填项，必须存在的六位占位符数字串。

    示例：
    源文件名：input.mp4，cmd为：vsample/jpg/ss/7/t/600/s/480x360/savePattern/JChrZXliYXNlKSQoY291bnQpLmpwZw==，其中 JChrZXliYXNlKSQoY291bnQpLmpwZw== ，是自定义截图后的文件名， $(keybase)$(count).jpg 的URL安全的Base64编码。最后得到类似：input000000.jpg,input000001.jpg,……,input000006.jpg 跟源文件命名是关联的的截图文件。

    操作方式

    您可以通过以下几种方式来创建任务：

    方式一：使用任务触发器

    • 对符合规则策略的上传文件自动触发：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 任务触发器；创建完成后，需要开启 上传触发开关，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

      img

    方式二：使用对象存储控制台

    • 上传文件手动触发：在具体空间下， 上传文件 时，指定工作流模板 。

      img

    • 指定文件手动触发：有两种指定单个文件创建任务的入口

      • 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

        img

        注意：仅对音视频/gif动图/webp动图文件提供该操作。

      • 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

        img

    方式三：使用API

    • 资源上传时手动触发：可以在构造上传凭证时在上传策略中，设置相关字段，在资源文件上传时触发处理。
    • 对已有资源手动触发：可以在调用 持久化数据处理(pfop) 时，设置相关字段，对已存在空间中的资源文件发起处理。

    方式四：使用SDK

    • 查看各语言 SDK 使用指南中 持久化数据处理 章节，可在七牛官方SDK 进行下载。

    操作示例

    示例1

    以 资源上传时手动触发，取视频第7秒到第607秒之间，以5秒为间隔的截图（即第7秒、第12秒、第17秒……依此类推），图片格式为jpg，宽度为480px，高度为360px，文件命名模板为 $(keybase) $(count).jpg：

    上传的token中指定persistentOps

    {
"scope":                "qiniu-ts-demo:thinking-in-go.mp4",
"deadline":             1390528576,
"persistentOps":      "vsample/jpg/ss/7/t/600/s/480x360/savePattern/JChrZXliYXNlKSAkKGNvdW50KS5qcGc=",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}

    示例2

    以 对已有资源手动触发 形式，将一段视频，平均截帧成8张图片，图片宽高和原图保持一致，图片格式为png：

    通过 workflowTemplateID 字段，指定工作流模板（仅支持V1版本工作流）

    POST /pfop/ HTTP/1.1
Host: api.qiniu.com  
Content-Type: application/x-www-form-urlencoded  
Authorization: Qiniu <AccessToken>  

bucket=qiniu-ts-demo&key=thinking-in-go.mp4&workflowTemplateID=vsample&notifyURL=http://fake.com/qiniu/notify

    计费说明

    视频采样缩略图，以 截取图片总张数 来计量计费。比如视频截取了100张小图，则最终计量是100次。服务价格=视频截图价格，定价参考 智能多媒体服务定价 。

    以上内容是否对您有帮助？
    • Close