`POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/remove-image-background` 本 API 用于提交一个同步的图像背景移除（抠图）任务，能够自动识别并保留图像主体，同时移除背景，生成背景透明的图片。 > **说明** > 如需了解完整应用示例和使用方式，请参阅[图像背景移除（智能抠图）](https://docs.volcengine.com/docs/6448/2407253)。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`image_url` |String |是 |`https://example.com/source.jpg` |待处理的图像 URL。

* **图像来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、火山引擎对象存储 (`tos://`) 三种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* **支持格式**：支持 `.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 分账](https://docs.volcengine.com/docs/6448/2519520)。 | ## 请求示例 ### 示例 1：通用场景抠图使用 `general` 场景对一张未知主体的图片进行背景移除。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/remove-image-background' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/object.jpg", "scene": "general" }' ``` ### 示例 2：人像抠图并添加描边使用 `human` 场景抠出人像，并为其添加一个 5px 宽的白色描边。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/remove-image-background' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/portrait.jpg", "scene": "human", "need_contour": true, "contour_color": "#FFFFFF", "contour_size": 5 }' ``` ### 示例 3：商品抠图并裁剪背景使用 `product` 场景抠出商品，并裁剪掉多余的透明背景区域。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/remove-image-background' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/gadget.png", "scene": "product", "need_crop_background": true }' ``` ## 响应说明这是一个同步接口，处理结果将直接在本接口的响应体中返回。 ### 响应参数 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否成功。

* `true`：成功。请查看 `result` 字段以获取任务结果。

* `false`：失败。请查看 `error` 字段以获取详细错误信息。 | |`result` |Object |包含图像处理结果的对象，仅在 `success` 为 `true` 时返回。详见下文 [Result 对象](https://docs.volcengine.com/docs/6448/2464627#db688b77)。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 [Error 对象](https://docs.volcengine.com/docs/6448/2464627#8ed75d41)。 | |`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`。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如：BadRequest。 | |`message` |String |对错误的详细描述，可用于开发调试。 | ### 响应示例成功响应示例： ```JSON { "success": true, "task_id": "amk-tool-remove-image-background-1716289900", "task_type": "remove-image-background", "result": { "image_url": "https://output.volcvideo.com/removed_bg_image.png?auth_key=...", "image_size": 45875, "image_format": "png", "image_width": 800, "image_height": 600 }, "expires_at": 1778573984, "queue_id": "q2a028fa533b7fe6a25b018dccd6284", "request_id": "20240521183140AABBCCDDEEFF778899" } ``` 失败响应示例： ```JSON { "success": false, "request_id": "20240521183200AABBCCDDEEFF112233", "task_type": "remove-image-background", "error": { "code": "InvalidParameter", "message": "Parameter 'scene' must be one of [general, human, product].", "param": "scene", "type": "BadRequest" }, "queue_id": "q2a028fa533b7fe6a25b018dccd6284" } ```