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

本 API 用于提交一个同步的图像打码任务。您可以对整张图像或指定矩形区域进行马赛克（打码）处理，并自定义像素格的形状与大小。该工具适用于遮挡人脸、证件信息、车牌、聊天记录等敏感内容。

请求参数

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。支持格式：支持 .png、.jpg、.jpeg、.webp 等主流图像格式。仅支持处理静图。分辨率：输入图像的宽和高均不得超过 10000 像素。
mosaic_type	String	否	specify-region	打码范围。 full-image：（默认值）对整张图片打码。 specify-region：仅对 mosaic_regions 指定的区域打码。
mosaic_regions	Array	否	[{"top_left_x": 100, ...}]	指定区域打码的矩形坐标列表，当 mosaic_type 为 specify-region 时必填。最多支持 3 个矩形区域。详细结构见下方的 Mosaic region 对象。
mosaic_shape	String	否	rectangle	打码像素格的形状。默认为 circle。 • circle：圆形/椭圆像素格，视觉更柔和。 • rectangle：矩形像素格，遮挡更规整。
mosaic_step_x	Integer	否	16	打码像素格的宽度，单位为 px。数值越大，马赛克颗粒感越强。默认为 12。不得小于 1。
mosaic_step_y	Integer	否	16	打码像素格的高度，单位为 px。数值越大，马赛克颗粒感越强。默认为 12。不得小于 1。
output_format	String	否	jpeg	输出图片的格式。默认为 original。 original：保持与原图一致的格式。 png jpeg webp
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

Mosaic region 对象

参数	类型	是否必选	示例值	描述
top_left_x	Integer	是	100	框选区域左上角的横 X 轴坐标，单位为 px。坐标原点为图像左上角。不得小于 0。
top_left_y	Integer	是	150	框选区域左上角的 Y 轴坐标，单位为 px。坐标原点为图像左上角。不得小于 0。
bottom_right_x	Integer	是	300	框选区域右下角的 X 轴坐标，单位为 px。坐标原点为图像左上角。不得小于 0。
bottom_right_y	Integer	是	250	框选区域右下角的 Y 轴坐标，单位为 px。坐标原点为图像左上角。不得小于 0。

假设您想要将下图蓝色区域作为打码区域，则参数设置如下：

top_left_x: 矩形左上角的 X 坐标（图中 b1）。

top_left_y: 矩形左上角的 Y 坐标（图中 a1）。

bottom_right_x: 矩形右下角的 X 坐标（图中 b2）。

bottom_right_y: 矩形右下角的 Y 坐标（图中 a2）。

请求示例

以下示例演示了如何对图片指定的一个矩形区域（左上角 (100, 150)，右下角 (300, 250)）应用 16x16 的矩形马赛克，并以 JPEG 格式输出。

响应说明

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

响应参数

参数	类型	描述
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	生成图像的格式，例如：webp。
image_width	Integer	生成图像的宽度，单位为 px。
image_height	Integer	生成图像的高度，单位为 px。

Error 对象

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

响应示例

成功响应示例：

失败响应示例：

AI MediaKit