`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames` 本 API 用于提交一个异步的视频抽帧任务。您可以根据不同的业务场景，选择**按时间间隔**、**按指定时间点**、**按指定帧（首/尾帧）** 或**按场景变化**四种策略，从视频中截取一或多张静态图片。截取的图片可用于视频封面、预览图、雪碧图或作为其他视频理解任务的输入。

说明

如需了解完整的使用流程和应用示例，请参阅视频抽帧。

## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |video_url |String |是 |`https://example.com/your_video.mp4` |待处理的视频 URL。

* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* **支持格式**：mp4, mov, mkv, flv, ts, avi, wmv 等主流视频格式。 | |`snapshot_type` |String |否 |`TimeInterval` |截图策略，决定抽帧的具体方式。默认为 `TimeInterval`。

* `TimeInterval`：按时间间隔抽帧，需配合 `time_interval` 参数。

* `SpecifiedTime`：按指定时间点抽帧，需配合 `specified_time` 参数。

* `SpecifiedFrames`：按指定帧号抽帧，需配合 `specified_frames` 参数。

* `SceneChange`：按场景变化抽帧，需配合 `scene_change_threshold` 参数。 | |`time_interval` |Number |否 |`10` |时间间隔，单位为秒，支持最多 3 位小数。默认值为 1，取值需大于 0.001。仅在 `snapshot_type` 为 `TimeInterval` 时**生效**。 | |`specified_time` |Array |否 |`[10.5, 25.0, 60.123]` |指定的时间点列表，单位为秒，支持最多 3 位小数。例如 `[10.5, 25.0, 60.123]`。最多支持 1000 个时间点。仅在 `snapshot_type` 为 `SpecifiedTime` 时生效且必填。 | |`specified_frames` |Array |否 |`[0, -1]` |指定的帧号列表。最多支持 2 个值。仅在 `snapshot_type` 为 `SpecifiedFrames` 时生效且必填。当前仅支持传入 `0`（视频首帧）和 `-1`（视频尾帧）。 | |`scene_change_threshold` |Number |否 |`0.2` |场景变化检测的敏感度阈值。取值范围为 (0, 1)，默认值为 0.1。值越小，对场景变化的检测越敏感，可能产生更多的截图。仅在 `snapshot_type` 为 `SceneChange` 时生效。 | |`snapshot_limit` |Integer |否 |`50` |生成截图的最大数量。取值范围 [1, 1000]，实际输出的截图数可能小于此值。

* 仅在 `snapshot_type` 为 `TimeInterval` 或 `SceneChange` 时生效。

* 开启雪碧图时（`enable_sprite` 为 `true`），此参数表示生成雪碧图**大图**的数量上限，因此雪碧图小图的数量上限为 `snapshot_limit*sprite_rows*sprite_cols`。 | |`scale_long` |Integer |否 |`1280` |输出图片长边的最大像素值，取值范围 [0, 4096]。如不传，则保持原始视频分辨率。

输出图片的长边不能超过原始视频的长边。例如，`scale_long` 设为 1280，则输出图片的长边将被缩放至 1280 像素，短边按原始比例自适应。

如果同时设置 `scale_long` 和 `scale_short`，则图片将在保持原始宽高比的前提下，确保长边不超过 `scale_long` 且短边不超过 `scale_short`。

开启雪碧图时（`enable_sprite` 为 `true`），此参数定义的是**单张小图**的长边。 | |`scale_short` |Integer |否 |`720` |输出图片短边的最大像素值，取值范围 [0, 4096]。如不传，则保持原始视频分辨率。

输出图片的短边不能超过原始视频的短边。例如，`scale_short` 设为 640，则输出图片的短边将被缩放至 640 像素，长边按原始比例自适应。

如果同时设置 `scale_long` 和 `scale_short`，则图片将在保持原始宽高比的前提下，确保长边不超过 `scale_long` 且短边不超过 `scale_short`。

开启雪碧图时（`enable_sprite` 为 `true`），此参数定义的是**单张小图**的短边。 | |`enable_sprite` |Boolean |否 |`true` |是否将截取的图片合成为一张雪碧图。默认为 `false`。

* `false`：输出多张独立的截图。

* `true`：输出包含所有截图的雪碧图。 | |`sprite_rows` |Integer |否 |`10` |雪碧图的行数（Y 轴垂直方向的小图数量）。默认值为 10，取值范围为 [1, 100]。仅在 `enable_sprite` 为 `true` 时生效。

**注意**：雪碧图最终尺寸有上限（建议单边不超过 16384 像素），设置过大的行列数可能导致任务失败。 | |`sprite_cols` |Integer |否 |`10` |雪碧图的列数（X 轴水平方向的小图数量）。默认值为 10，取值范围为 [1, 100]。仅在 `enable_sprite` 为 `true` 时生效。

**注意**：雪碧图最终尺寸有上限（建议单边不超过 16384 像素），设置过大的行列数可能导致任务失败。 | |`client_token` |String |否 |`your_unique_request_id_131` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_unique_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://docs.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://docs.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://docs.volcengine.com/docs/6448/2519520)。 | ## 请求示例 ### 示例 1：按时间间隔抽帧以下示例演示了如何从视频的第 0 秒开始，每 10 秒截取一帧，最多截取 5 帧，并设置输出图片长边为 640 像素。 ```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://example.com/your_video.mp4", "snapshot_type": "TimeInterval", "time_interval": 10, "snapshot_limit": 5, "scale_long": 640 }' ``` ### 示例 2：按指定时间点生成雪碧图以下示例演示了如何在视频的特定时间点（10.5s, 25s, 60.123s, 120s）截取 4 帧，并将它们合成为一张 2x2 的雪碧图。 ```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://example.com/your_video.mp4", "snapshot_type": "SpecifiedTime", "specified_time": [10.5, 25.0, 60.123, 120.0], "enable_sprite": true, "sprite_rows": 2, "sprite_cols": 2 }' ``` ## 响应说明调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。 ### 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |`success` |Boolean |任务是否成功提交。

* `true`：任务已成功提交到后台处理队列。

* `false`：请求存在错误，任务提交失败。请检查 `error` 字段以获取详细信息。 | |`task_id` |String |任务的唯一标识符。仅在 `success` 为 `true` 时返回有效值。您可以使用此 ID 来查询任务状态和结果。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 Error 对象。 | #### Error 对象 |**参数** |**类型** |**描述** | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)， | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例 #### 成功响应 ```JSON { "success": true, "task_id": "amk-tool-extract-frames-123456789", "request_id": "20240523100000ABCDEFG12345" } ``` #### 失败响应 ```JSON { "success": false, "task_id": "", "request_id": "20240523101000WXYZ54321", "error": { "code": "InvalidParameter", "message": "The 'xxx' parameter is required xxx", "param": "time_interval", "type": "BadRequest" } } ``` ## 异步任务结果视频抽帧是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果： * **方法一（轮询查询）：** 使用提交任务时获取的 `task_id`，定期调用[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到 `status` 字段变为 `completed` 或 `failed`。 * **方法二（事件回调）：** 在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 `callback_url` 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅[事件回调](https://docs.volcengine.com/docs/6448/2288701)。当任务成功完成后，您获取到的任务信息中的 `result` 字段将包含以下内容。 |参数 |类型 |描述 | |---|---|---| |`snapshots` |Array |截图结果列表。每个对象包含一张截图的信息。详见下文[Snapshot 对象](https://docs.volcengine.com/docs/6448/2515376#gPKWcFLOhr)。 | |`snapshot_count` |Integer |成功生成的截图总数。如果是雪碧图模式，该值为雪碧图中的小图数量。 | ### Snapshot 对象 |参数 |类型 |描述 | |---|---|---| |`image_url` |String |截图下载地址。该地址的有效期为 **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=..." }, { "image_url": "https://example.com/snapshot/frame_20s.jpg?sign=..." } ], "snapshot_count": 3 }, "expires_at": 1777531298, "created_at": 1777358413, "finished_at": 1777359999 } ``` 以下是一个**雪碧图**抽帧任务执行完成后的完整任务信息示例： > 当请求参数 `enable_sprite` 为 `true` 时，`snapshots` 数组中的 `image_url` 指向合成后的雪碧图大图。 ```JSON { "success": true, "task_id": "amk-tool-extract-frames-987654321", "request_id": "20240523100500XYZABC12345", "status": "completed", "result": { "snapshots": [ { "image_url": "https://example.com/snapshot/sprite.jpg?sign=..." } ], "snapshot_count": 4 }, "expires_at": 1777531300, "created_at": 1777358420, "finished_at": 1777358900 } ```