文档中心

AI MediaKit

图像工具 API

提交图像人脸打码任务 API

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

本 API 用于提交一个同步的图像人脸打码任务，自动检测图片中的所有人脸区域并进行马赛克处理，实现一键人脸隐私保护。适用于社交平台内容审核、街景/监控画面脱敏、新闻媒体素材处理、AI 训练数据集脱敏等需要批量保护人脸隐私的场景。

说明

如需了解完整应用示例和使用方式，请参阅图像人脸打码。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/source.jpg	待打码的图像 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。文件大小：建议不超过 35 MB，图片文件过大可能导致处理失败。分辨率限制：图片宽度和高度的乘积不得超过 4 亿像素。支持格式：支持 .png、.jpg、.jpeg、.webp 、.avif 等主流图像格式，不支持动图。
blur_shape	String	否	circle	人脸模糊区域的形状。 circle：（默认）圆形 rectangle：矩形
mosaic_step	Integer	否	12	马赛克像素格大小，单位 px，正整数。值越大马赛克颗粒越大、脱敏强度越高。建议范围 [5, 100]，默认 12。
face_detect_thresh	Number	否	0.9	人脸检测置信度阈值，取值范围 (0, 1)。值越高过滤越严格：过低可能误判非人脸区域，过高可能漏检人脸。默认 0.9。
output_format	String	否	webp	输出图片格式。可选值： png jpeg webp（默认）

请求示例

响应说明

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

响应参数

参数	类型	描述
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 对象

参数	类型	描述
image_url	String	人脸打码后的图片文件下载地址。该地址的有效期为 24 小时，请务必及时保存产物。
image_size	Integer	处理后图片大小，单位字节。
image_format	String	处理后图片格式。
image_width	Integer	处理后图片宽度，单位 px。
image_height	Integer	处理后图片高度，单位 px。
face_count	Integer	检测到并已打码的人脸数量。0 表示未检测到人脸、原图未做处理；大于 0 表示已对对应数量人脸完成打码。
face_location	Array	每张检测出的人脸信息对象数组；未检测到人脸时为空数组。详见下文 Face location 对象。

Face location 对象

Error 对象

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

响应示例

成功响应示例：

失败响应示例：

最近更新时间：2026.09.22 17:01:53

这个页面对您有帮助吗？

有用

无用