POST https://mediakit.cn-beijing.volces.com/api/v1/tools/extract-frames

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

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/your_video.mp4	待处理的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：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<Number>	否	[10.5, 25.0, 60.123]	指定的时间点列表，单位为秒，支持最多 3 位小数。例如 [10.5, 25.0, 60.123]。最多支持 1000 个时间点。仅在 snapshot_type 为 SpecifiedTime 时生效且必填。
specified_frames	Array<Integer>	否	[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_limitsprite_rowssprite_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 像素），设置过大的行列数可能导致任务失败。
media_output_destination	String	否	tos://<您的桶名>	指定处理产物（截图/雪碧图）的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 不传本参数时，任务结果中的 image_url 返回有效期为 24 小时的临时下载地址。设置本参数后，产物将写回您的 VOD 空间或 TOS 桶，任务结果中的 image_url 将返回形如 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。请前往 AI MediaKit 控制台基础配置 > 授权管理页面，根据您的需要，为 AI MediaKit 服务授予相应的权限。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_131	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_unique_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考按项目或 API Key 分账。

请求示例

示例 1：按时间间隔抽帧

以下示例演示了如何从视频的第 0 秒开始，每 10 秒截取一帧，最多截取 5 帧，并设置输出图片长边为 640 像素。

示例 2：按指定时间点生成雪碧图

以下示例演示了如何在视频的特定时间点（10.5s, 25s, 60.123s, 120s）截取 4 帧，并将它们合成为一张 2x2 的雪碧图。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码，
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

视频抽帧是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。

参数	类型	描述
snapshots	Array	截图结果列表。每个对象包含一张截图的信息。详见下文Snapshot 对象。
snapshot_count	Integer	成功生成的截图总数。如果是雪碧图模式，该值为雪碧图中的小图数量。

Snapshot 对象

参数	类型	描述
image_url	String	截图下载地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载地址，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回写回到您 VOD 空间或 TOS 桶的存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。

以下是一个普通抽帧任务执行完成后的完整任务信息示例：

以下是一个雪碧图抽帧任务执行完成后的完整任务信息示例：

AI MediaKit