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

本 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://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp 和 .heic。文件大小：单张图片不得超过 30 MB。图像输入分辨率：当 scene 为 general：输入图像分辨率的长边不得超过 10240 px、短边不得超过 6000 px。输入图像的总像素数量（长边 × 短边）不得超过 40 MP。当 scene 为 human 或 product：图像输入分辨率的长边不得超过 7680 px、短边不得超过4320px。
scene	String	是	human	背景移除场景。 general：通用场景。适用于期望抠出图像主体，但不确定该主体所属分类的场景。 human：人像抠图场景。适用于仅需抠出图像中的人像主体的场景。 product：商品抠图场景。适用于仅需抠出图像中的商品主体的场景。
need_contour	Boolean	否	true	是否为主体生成描边。默认为 false。注意此参数仅在 scene 为 human 或 product 时生效，在 general 场景下会被忽略。
contour_color	String	否	#FFFFFF	主体描边的颜色，使用十六进制 RGB 格式。默认为 "#FFFFFF"（白色）。注意此参数仅当 need_contour 为 true 且 scene 为 human 或 product 时生效。
contour_size	Integer	否	10	主体描边的宽度，单位为像素（px）。取值范围为 [1, 100]，默认为 10。注意此参数仅当 need_contour 为 true 且 scene 为 human 或 product 时生效。
need_crop_background	Boolean	否	true	是否将输出图片的透明背景裁剪到刚好包裹住主体。默认为 false。注意此参数仅在 scene 为 human 或 product 时生效，在 general 场景下会被忽略。
output_format	String	否	png	输出图片的格式。 png：（默认）支持透明背景。 jpeg：不支持透明背景，透明区域将填充为黑色。 webp：支持透明背景。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考按项目或 API Key 分账。

请求示例

示例 1：通用场景抠图

使用 general 场景对一张未知主体的图片进行背景移除。

示例 2：人像抠图并添加描边

使用 human 场景抠出人像，并为其添加一个 5px 宽的白色描边。

示例 3：商品抠图并裁剪背景

使用 product 场景抠出商品，并裁剪掉多余的透明背景区域。

响应说明

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

响应参数

参数	类型	描述
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	45875	生成图像的大小，单位为字节。
image_format	String	png	生成图像的格式。
image_width	Integer	800	生成图像的宽度，单位为像素（px）。
image_height	Integer	600	生成图像的高度，单位为像素（px）。

Error 对象

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

响应示例

成功响应示例：

失败响应示例：

AI MediaKit