POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/probe-image-metadata

本 API 用于提交一个同步的图像元信息获取任务，支持查询图像的基础元数据（metadata）、主题色（avghue）、透明通道（alpha）以及 BlurHash（blurhash）四种信息。可广泛应用于素材管理、AIGC 元数据识别、透明通道分析、主题色提取和低成本预览图生成等场景。这是一个同步接口，处理结果将直接在本接口的响应体中返回。

注意事项

获取图像基础元数据（info_type 为 metadata）的特殊说明

获取色彩模型：仅支持处理 jpeg、webp、png、heic 和 avif 格式。各格式支持返回的色彩模型如下：

jpeg：gray、ycbcr、rgba、cmyk

webp：ycbcr、nycbcra、nrgba

png：rgba、rgba64、nrgba、nrgba64、gray、gray16、palette

heic：ycbcr

avif：ycbcr

获取压缩质量参数：仅支持处理 jpeg 格式。

获取 AIGC 元数据：请确保您的图片格式和 AIGC 元数据位置符合以下要求：

jpeg：AIGC 元数据需位于 XMP 元素/属性字段、App 11 字段或 EXIF 的 Usercomment 字段。

png：AIGC 元数据需位于 XMP 元素/属性字段、tEXt chunk 信息或 EXIF 的 Usercomment 字段。

webp：AIGC 元数据需位于 XMP 元素/属性字段或 EXIF 的 Usercomment 字段。

avif/heic：AIGC 元数据需位于 EXIF 的 Usercomment 字段。

注意：如果 jpeg 或 png 图片的 XMP 字段中已包含 AIGC 元数据，系统将仅从该字段获取，不再检查其他位置。

获取动图元信息的特殊说明

若输入为动图（如 GIF），不同 info_type 的处理逻辑存在差异：

info_type 为 metadata：可获取动图的帧数（frame_count）和时长（duration）等元信息。

info_type 为 alpha：不支持对动图进行透明通道分析。

info_type 为 avghue 和 blurhash：仅处理动图的首帧，并将其作为静态图片返回分析结果。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/image.png	待探测的图片 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。文件大小：建议单张图片不超过 35 MB。支持格式：支持 .png、.jpg、.jpeg、.webp 等主流图像格式。动图的具体处理逻辑请参考获取动图元信息的特殊说明。输入分辨率限制：宽和高均不得超过 10000 像素。
info_type	String	否	metadata	查询信息的类型，默认为 metadata。 metadata：获取图像的基本元信息。具体限制请见获取图像基础元数据（info_type 为 metadata）的特殊说明。 avghue：提取图像的主题色。 alpha：分析图像的 Alpha 透明通道。 blurhash：生成图像的 BlurHash 值。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

响应说明

这是一个同步接口，处理结果将直接在本接口的响应体中返回。

响应参数

参数	类型	描述
success	Boolean	任务是否成功。 true：成功。请查看 result 字段以获取任务结果。 false：失败。请查看 error 字段以获取详细错误信息。
result	Object	包含图像处理结果的对象，仅在 success 为 true 时返回。详见下文 Result 对象。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。
task_id	String	任务的唯一标识。
task_type	String	任务类型。
request_id	String	本次 API 请求的唯一标识，可用于问题排查。
expires_at	Integer	任务结果的过期时间戳（Unix Time，单位：秒）。仅当任务成功且有结果时返回。
queue_id	String	任务提交的目标队列 ID。

Result 对象

当 info_type 为 metadata（默认）

返回图像的基础元数据信息。

参数	类型	描述
width	Number	图片宽度，单位为 px。
height	Number	图片高度，单位为 px。
format	String	图片格式，例如 jpeg。
size	Number	图片大小，单位为 Byte。
md5	String	图片的 MD5 值。
frame_count	Number	图片帧数。对于静态图，通常为 1。
color_model	String	色彩模型，例如 gray。
duration	Number	动图时长，单位为秒。静态图此字段可能不存在。
orientation	Any	图片方向信息。
quality	Number	压缩质量参数。
exif	Object \| Null	EXIF 元数据。如果不存在则为 null。
aigc	Object \| Null	AIGC 元数据。如果不存在则为 null。

metadata 示例

当 info_type 为 avghue

返回图像的十六进制主题色。

参数	类型	描述
color	String	十六进制格式的主题色，例如 #RRGGBB。

avghue 示例

当 info_type 为 alpha

返回图像的 Alpha 透明通道信息。

参数	类型	描述
format	String	图片格式。
width	Number	图片宽度，单位为 px。
height	Number	图片高度，单位为 px。
is_animation	Boolean	是否为动图。
has_alpha	Boolean	是否包含 Alpha 透明通道。
alpha_ratio	Number	Alpha 像素（完全透明或半透明）在整张图片中的占比。

alpha 响应示例

当 info_type 为 blurhash

返回图像的 BlurHash 字符串。

参数	类型	描述
blurhash	String	BlurHash 编码字符串。

blurhash 示例

Error 对象

参数	类型	描述
code	String	具体的错误码，用于程序化识别错误类型。例如：InvalidParameter。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如：BadRequest。
message	String	对错误的详细描述，可用于开发调试。

AI MediaKit