文档中心

AI MediaKit

视频工具

视频抽帧

AI MediaKit 的视频抽帧工具，可以从视频中截取一张或多张静态图片。您可以根据不同的业务场景，选择按时间间隔、按指定时间点、按指定帧（首/尾帧）或按场景变化四种策略进行抽帧。截取的图片可用于生成视频封面、预览图、雪碧图，或作为其他视频理解任务的输入。

本篇开发指南将引导您：

快速体验如何按固定时间间隔从视频中抽帧。

掌握使用不同策略进行抽帧的核心参数。

快速入门：按时间间隔均匀抽帧

本节以“按时间间隔抽帧”为例，演示如何从一段视频中每隔 10 秒截取一帧。

准备工作

获取访问凭证：在开始之前，请访问 AI MediaKit 控制台的 API Key 管理页面，创建并获取 MediaKit API Key。

准备视频文件：准备一个待处理的视频文件，并将其上传至公网可访问的服务器或视频点播服务中，以获取可供 API 调用的 URL。为方便您快速测试，本文后续步骤的示例代码中提供了一个可直接使用的演示视频 URL。

操作流程

视频抽帧是一个异步任务，其标准流程如下：

成功调用 POST /api/v1/tools/extract-frames 提交任务后，您将获得一个任务 ID。

您可以轮询 GET /api/v1/tasks/{task_id} 接口，直到任务状态status 变为 completed；或者使用事件回调自动接收任务状态变化。

任务完成后，解析响应中的 result 字段，即可在 snapshots.image_url 中获取截图的下载地址。

第 1 步：提交抽帧任务

您需要调用提交视频抽帧任务 API。可直接复制以下 cURL 命令，提交一个从视频中每 10 秒截取一帧的任务。

说明

将 {Your_API_Key} 替换为您的有效 API Key。

video_url：示例中已提供可直接用于测试的演示视频 URL。您也可以将其替换为您自己的视频地址。

请求成功后，您会收到如下包含 task_id 的响应，请保存此 ID 用于后续查询。

第 2 步：获取抽帧结果

抽帧任务需要一定的处理时间。您需要轮询查询任务信息 API，直到任务状态 status 变为 completed。

说明

需替换参数：将 URL 末尾的 {task_id} 替换为第 1 步返回的任务 ID。

当任务成功完成后，您将收到如下响应。result.snapshots 数组中的每个对象都包含一个 image_url，即截取到的图片下载地址（默认输出为 JPG 格式，有效期为 24 小时）。

本示例中，输入视频时长 16 秒，任务请求中指定每 10 秒截取一帧，因此共返回 2 张图片，效果如下：

第一张	第二张

进阶使用：更多抽帧策略

抽帧的基本流程（提交任务 -> 查询结果）与“快速入门：按时间间隔均匀抽帧”章节完全相同。本节将为您展示不同策略下的完整请求示例。

按指定时间点抽帧

此策略用于截取您精确指定的某几个时间点的画面。以下示例演示了如何在视频的 5 秒、10 秒和 15 秒处各截取一帧。

按指定帧（首/尾帧）抽帧

此策略用于快速获取视频的第一帧（0）或最后一帧（-1），常用于生成视频封面。

按场景变化抽帧

此策略通过智能算法自动检测视频中的场景切换点，并截取每个新场景的起始帧。scene_change_threshold 的值越小，检测越敏感。以下示例演示了如何使用默认的敏感度 0.1 进行场景抽帧。

生成雪碧图

雪碧图是由多张截图按一定行列顺序拼接而成的一张大图。在播放器中，它常用于实现进度条预览功能，允许用户在拖动进度条时快速查看视频缩略图，具有以下优势：

减少网络请求：将多张小图合并为一张大图，客户端只需请求一次即可获取所有预览帧，显著降低了服务器压力并提升加载速度。

优化存储与压缩：单张大图相比于海量小图，更易于管理和存储，且通常能获得更好的压缩效果。

以下示例展示了如何从视频中每 10 秒截取一帧，并将这些截图合成为一个 5x5 的雪碧图。

说明

enable_sprite 设为 true 即可开启雪碧图生成功能。

sprite_rows/sprite_cols 分别定义雪碧图的行数和列数，用于排列小图。

如果需要控制单张小图的尺寸，可使用 scale_long 和 scale_short 参数。注意：雪碧图的最终尺寸（宽或高）建议不要超过 16384 像素，否则可能导致任务失败。您可以通过调整行列数以及缩放参数来控制最终尺寸。

任务成功后，查询结果中的 result.snapshots.image_url 将指向生成的雪碧图大图地址。本示例中，输入视频时长 2 分 32 秒，任务请求中指定每 10 秒截取一帧，因此共生成 16 张截图；雪碧图的行数和列数分别为 5，因此最终返回 1 张雪碧图。效果如下：

参考信息

使用限制

限制项	说明
输入视频限制	视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, mov, mkv, flv, ts, avi, wmv 等主流视频格式。
截图数量限制	通过 snapshot_limit 参数可限制 TimeInterval 和 SceneChange 策略生成的截图最大数量，上限为 1000。SpecifiedTime 策略最多支持 1000 个时间点。
雪碧图限制	当 enable_sprite 设为 true 时，系统会生成雪碧图。建议雪碧图的最终尺寸（宽或高）不要超过 16384 像素，否则可能导致任务失败。您可以通过调整 sprite_rows、sprite_cols 以及缩放参数（scale_long/scale_short）来控制最终尺寸。