智能多媒体服务

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

    视频采样缩略图（vsample）

    最近更新时间: 2026-08-18 15:25:04

    简介

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

    参数说明

    vsample/<Format>
       /ss/<StartTime>
       /t/<Duration>
       /s/<Resolution>
       /rotate/<Degree>
       /interval/<Interval>
       /frames/<Frames>
       /savePattern/<savePattern>
    参数名称必填说明
    <a id="video-sample-format"></a>`<Format>`是输出的目标截图格式，支持`jpg`、`png`等。
    <a id="video-sample-starttime"></a>`/ss/<StartTime>`指定截取视频的开始时刻，单位：秒,精度为 100ms，例如 `/ss/1.1`；默认从片头开始。
    <a id="video-sample-duration"></a>`/t/<Duration>`采样总时长，单位：秒,精度为 100ms，例如 `t/1.1`；默认表示到片尾结束。
    <a id="video-sample-resolution"></a>`/s/<Resolution>`0. 指定截图分辨率，格式为宽 x 高 ，长边取值范围[20,3840]的整数，短边取值范围[20,2160]的整数。
    1. 宽、高都为空时，则和原视频保持一致
    2. 宽为空，高不为空，则按高的值对原视频等比例缩放
    3. 宽不为空，高为空时，则按宽的值对原视频等比例缩放
    4. 宽、高都不为空时，则根据宽、高来缩放
    <a id="video-sample-rotate"></a>`/rotate/<Degree>`指定顺时针旋转的度数，可取值为`90`、`180`、`270`、`auto`。
    默认为不旋转。
    <a id="video-sample-interval"></a>`/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. 建议截帧帧率是视频帧率的整数倍。
    <a id="video-sample-pattern"></a>`/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次。服务价格=视频截图价格，定价参考 智能多媒体服务定价 。

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