POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/erase-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://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。图像输入分辨率：不得小于 10x10 像素不得超过 2560x1440 像素（宽x高）文件大小：单张图片不得超过 10 MB。支持格式：支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp 和 .heic。
tool_version	String	否	standard	图像擦除修复选用的模型版本。当前仅支持 standard（标准版），适用于简单、明确的擦除任务。
standard_scene	String	否	full_screen_text_erase	标准版擦除场景，仅当 tool_version 为 standard 时生效。默认值为 full_screen_text_erase。 full_screen_text_erase：全屏文字擦除。可通过 standard_erase_text 字段指定要擦除的文字，不指定则默认擦除所有文字内容。 full_screen_icon_erase：全屏图标擦除。 selected_area_erase：指定区域擦除。使用此场景时，您必须至少提供 selected_area（矩形坐标）或 mask_url（遮罩图）中的一个参数来定义擦除范围。如果同时提供了这两个参数，系统将擦除它们所定义区域的并集。
standard_erase_text	String	否	"内部资料"	指定需要擦除的文字内容。仅当 standard_scene 为 full_screen_text_erase 时生效。若不提供此参数，则会擦除识别到的所有文字。
selected_area	Object	否	{"top_left_x": 0.1, "top_left_y": 0.1, "bottom_right_x": 0.5, "bottom_right_y": 0.4}	指定擦除区域（矩形框）。仅当 standard_scene 为 selected_area_erase 时生效。坐标系以输入图像的左上角为原点，宽度和高度均归一化为 [0,1]。例如，(0.5, 0.5) 代表图像中心点。详细定义见下文的 Selected area 对象。如果同时传入 mask_url，则擦除两个参数指定区域的并集。
mask_url	String	否	https://example.com/mask.png	遮罩图片 URL。通过上传一张黑白遮罩图，可以指定需要擦除的任意形状区域。仅当 standard_scene 为 selected_area_erase 时生效。遮罩图要求如下：图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。分辨率要求：必须与输入图像 image_url 的分辨率一致。如果同时传入 selected_area，则擦除两个参数指定区域的并集。
output_format	String	否	png	输出图片的格式。 webp（默认值） png jpeg
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

Selected area 对象

该对象用于定义一个矩形擦除区域。使用归一化的坐标系，以图片左上角为原点 (0, 0)，右下角为 (1, 1)。所有坐标值均为相对于图片总宽度或总高度的比例，取值范围为 [0.0, 1.0]。

参数	类型	是否必选	示例值	描述
top_left_x	Number	是	0.1	矩形框左上角的 X 坐标（横向位置）。该值为相对于图片总宽度的比例，
top_left_y	Number	是	0.1	矩形框左上角的 Y 坐标（纵向位置）。该值为相对于图片总高度的比例，
bottom_right_x	Number	是	0.5	矩形框右下角的 X 坐标（横向位置）。该值必须大于 top_left_x，
bottom_right_y	Number	是	0.4	矩形框右下角的 Y 坐标（纵向位置）。该值必须大于 top_left_y，取值范围 [0, 1]。

请求示例

示例 1：擦除图中所有文字（默认行为）

设置 standard_scene 为 full_screen_text_erase（或使用默认值），不传入 standard_erase_text。

示例 2：擦除图中指定文字

设置 standard_scene 为 full_screen_text_erase（或使用默认值），并传入 standard_erase_text 参数指定擦除内容。

示例 3：擦除图中所有图标

设置 standard_scene 为 full_screen_icon_erase。

示例 4：擦除指定区域（坐标框）

设置 standard_scene 为 selected_area_erase，并通过 selected_area 传入归一化坐标框。以下示例擦除图像左上部一块矩形区域。

示例 5：擦除指定区域（遮罩图）

设置 standard_scene 为 selected_area_erase，并通过 mask_url 传入遮罩图。

响应说明

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

响应参数

参数	类型	描述
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	https://output.volcvideo.com/...?auth_key=...	擦除修复后的图片下载 URL。该地址的有效期为 24 小时，请务必及时保存产物。
image_size	Integer	51200	生成图像的大小，单位为字节。
image_format	String	webp	生成图像的格式。
image_width	Integer	1920	生成图像的宽度，单位为像素（px）。
image_height	Integer	1080	生成图像的高度，单位为像素（px）。

Error 对象

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

响应示例

成功响应示例：

失败响应示例：

AI MediaKit