AI MediaKit 的视频抽帧工具，可以从视频中截取一张或多张静态图片。您可以根据不同的业务场景，选择**按时间间隔**、**按指定时间点**、**按指定帧（首/尾帧）或按场景变化**四种策略进行抽帧。截取的图片可用于生成视频封面、预览图、雪碧图，或作为其他视频理解任务的输入。本篇开发指南将引导您： * 快速体验如何按固定时间间隔从视频中抽帧。 * 掌握使用不同策略进行抽帧的核心参数。 ## 快速入门：按时间间隔均匀抽帧本节以“按时间间隔抽帧”为例，演示如何从一段视频中每隔 10 秒截取一帧。 ### 准备工作 1. **获取访问凭证**：在开始之前，请访问 AI MediaKit 控制台的 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 **MediaKit API Key**。 2. **准备视频文件**：准备一个待处理的视频文件，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。为方便您快速测试，本文后续步骤的示例代码中提供了一个可直接使用的演示视频 URL。 ### 操作流程视频抽帧是一个异步任务，其标准流程如下： 1. 成功调用 `POST /api/v1/tools/extract-frames` 提交任务后，您将获得一个任务 ID。 2. 您可以轮询 `GET /api/v1/tasks/{task_id}` 接口，直到任务状态`status` 变为 `completed`；或者使用[事件回调](https://www.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，解析响应中的 `result` 字段，即可在 `snapshots.image_url` 中获取截图的下载地址。 #### 第 1 步：提交抽帧任务您需要调用[提交视频抽帧任务 API](https://www.volcengine.com/docs/6448/2515376)。可直接复制以下 cURL 命令，提交一个从视频中每 10 秒截取一帧的任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/dragon.mp4", "snapshot_type": "TimeInterval", "time_interval": 10 }' ```

说明

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

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

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-extract-frames-123456789", "request_id": "20240523100000ABCDEFG12345" } ``` #### 第 2 步：获取抽帧结果抽帧任务需要一定的处理时间。您需要轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532)，直到任务状态 `status` 变为 `completed`。 ```Bash curl -X GET 'https://mediakit.cn-beijing.volces.com/api/v1/tasks/{task_id}' \ -H 'Authorization: Bearer {Your_API_Key}' ```

说明

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

当任务成功完成后，您将收到如下响应。`result.snapshots` 数组中的每个对象都包含一个 `image_url`，即截取到的图片下载地址（默认输出为 **JPG** 格式，有效期为 **24** 小时）。 ```JSON { "success": true, "task_id": "amk-tool-extract-frames-123456789", "request_id": "20240523100000ABCDEFG12345", "status": "completed", "result": { "snapshots": [ { "image_url": "https://example.com/snapshot/frame_0s.jpg?sign=..." }, { "image_url": "https://example.com/snapshot/frame_10s.jpg?sign=..." } ], "snapshot_count": 2 }, "expires_at": 1777531298, "created_at": 1777358413, "finished_at": 1777359999 } ``` 本示例中，输入视频时长 16 秒，任务请求中指定每 10 秒截取一帧，因此共返回 2 张图片，效果如下： |第一张 |第二张 | |---|---| |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/5b88f2bca4104aea9f06f28552962d70) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/b991aa6c5de8414e9e48a16785c0b4bf) | ## 进阶使用：更多抽帧策略抽帧的基本流程（提交任务 \-\> 查询结果）与“[快速入门：按时间间隔均匀抽帧](https://www.volcengine.com/docs/6448/2479865#xtEohFwPu9)”章节完全相同。本节将为您展示不同策略下的完整请求示例。 ### 按指定时间点抽帧此策略用于截取您精确指定的某几个时间点的画面。以下示例演示了如何在视频的 **5 秒**、**10 秒**和 **15 秒**处各截取一帧。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/dragon.mp4", "snapshot_type": "SpecifiedTime", "specified_time": [5, 10, 15] }' ``` ### 按指定帧（首/尾帧）抽帧此策略用于快速获取视频的第一帧（`0`）或最后一帧（`-1`），常用于生成视频封面。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/dragon.mp4", "snapshot_type": "SpecifiedFrames", "specified_frames": [0, -1] }' ``` ### 按场景变化抽帧此策略通过智能算法自动检测视频中的场景切换点，并截取每个新场景的起始帧。`scene_change_threshold` 的值越小，检测越敏感。以下示例演示了如何使用默认的敏感度 `0.1` 进行场景抽帧。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/dragon.mp4", "snapshot_type": "SceneChange", "scene_change_threshold": 0.1 }' ``` ### 生成雪碧图雪碧图是由多张截图按一定行列顺序拼接而成的一张大图。在播放器中，它常用于实现进度条预览功能，允许用户在拖动进度条时快速查看视频缩略图，具有以下优势： * **减少网络请求**：将多张小图合并为一张大图，客户端只需请求一次即可获取所有预览帧，显著降低了服务器压力并提升加载速度。 * **优化存储与压缩**：单张大图相比于海量小图，更易于管理和存储，且通常能获得更好的压缩效果。以下示例展示了如何从视频中每 10 秒截取一帧，并将这些截图合成为一个 5x5 的雪碧图。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/video_cloud.mp4", "snapshot_type": "TimeInterval", "time_interval": 10, "enable_sprite": true, "sprite_rows": 5, "sprite_cols": 5 }' ```

说明

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

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

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

任务成功后，查询结果中的 `result.snapshots.image_url` 将指向生成的雪碧图大图地址。本示例中，输入视频时长 2 分 32 秒，任务请求中指定每 10 秒截取一帧，因此共生成 16 张截图；雪碧图的行数和列数分别为 5，因此最终返回 1 张雪碧图。效果如下： ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/e24d430d967640a5bc7cf9c17d8eb3eb) ## 参考信息 ### 使用限制 |限制项 |说明 | |---|---| |输入视频限制 |* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://www.volcengine.com/docs/6448/2536893)。

* **支持格式**：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`）来控制最终尺寸。 | ## 相关 API 文档 * [提交视频抽帧任务 API](https://www.volcengine.com/docs/6448/2515376) * [查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) * [事件回调](https://www.volcengine.com/docs/6448/2288701)