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

本 API 用于提交一个异步的视频截取动图任务，按照指定的开始时间和结束时间从视频中截取一段画面，生成 GIF 或 WebP 格式的动图，常用于制作封面动图、营销素材、短预览等。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/source.mp4	待截取动图的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等。分辨率限制：输入视频最高支持 4K (3840×2160) 分辨率。
start_time	Number	是	10.5	截取片段的开始时间，单位为秒。支持最多 3 位小数。默认为 0，表示从视频开头截取。
end_time	Number	是	15.0	截取片段的结束时间，单位为秒。必须大于 start_time。支持最多 3 位小数。说明输出动图的时长最大为 60 秒。
output_format	String	否	webp	输出动图的格式。支持 gif 和 webp。默认值为 gif。
media_output_destination	String	否	tos://<您的桶名>	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的对象存储（TOS）桶。您可将 media_output_destination 设为 tos://<您的桶名>。任务结果中的 url 相关字段将返回形如 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_132	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_data	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何从视频的第 10.5 秒截取到第 15 秒，生成一个 webp 格式的动图。

响应说明

调用 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 字段将包含以下内容。

参数	类型	示例	描述
image_url	String	https://example.volcvideo.com/output.webp?auth_key=...	生成的动图文件地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 tos://<桶名>/<对象Key>。说明输出动图的帧率固定为 15 fps。
duration	Number	4.5	输出动图的时长，单位为秒，保留 3 位小数。根据 min(end_time, 视频总时长) - start_time 计算得出。
resolution	String	480p	输出动图的分辨率。输出动图的分辨率最大为 480p。输入视频的分辨率低于 480p 时，输出动图的分辨率则对齐输入视频。

最终的完整任务信息示例：

AI MediaKit