图片消除笔API

免费体验

AI 智能去除图片中不需要的物体、水印、瑕疵或杂物。通过蒙版图或矩形框标记去除区域后，输出自然修复后的结果图。适用于电商商品图、人像照片、设计素材等场景。支持异步、同步两种调用方式。

接口返回的链接有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建图片消除任务

POST /api/tasks/visual/inpaint

请求参数

image_url string 可选

源图像 URL。如果存在此参数，则 image_file 必须为空。

二选一必填

image_file file 可选

源图像文件（二进制）。如果此参数存在，则 image_url 必须为空。

图片上传要求请参看使用规范与限制#6。

mask_url string 可选

蒙版图像 URL。如果存在此参数，则其他去除区域参数必须为空。

去除区域要求请参看使用规范与限制#5。

三选一必填

mask_file file 可选

蒙版图像文件（二进制）。如果此参数存在，则其他去除区域参数必须为空。

去除区域要求请参看使用规范与限制#5。

三选一必填

rectangles string 可选

一个或多个矩形区域，用于指定需要擦除的区域，最多支持 50 个矩形区域。例如：[{"x":0,"y":0,"width":100,"height":100}]。如果存在此参数，则其他去除区域参数必须为空。

去除区域要求请参看使用规范与限制#5。

return_type integer 可选

结果返回方式。1 表示返回图片下载 URL；2 表示返回 base64 字符串。默认值为 1。

sync integer 可选

是否等待结果就绪并立即返回。0 表示异步返回 task_id，稍后通过查询接口获取结果；1 表示等待结果准备好后立即返回。请求提交后，结果最多只会保留 1 小时。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

返回说明。任务失败时可参考此字段或联系客服。

data.task_id string

图片消除任务 ID，用于轮询结果。

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

返回说明。任务失败时可参考此字段或联系客服。

data.task_id string

图片消除任务 ID。如果任务失败，请携带此参数联系客服。

data.created_at string

任务创建时间戳。

data.processed_at string

任务开始处理时间戳。

data.completed_at string

任务完成时间戳。

data.image string

结果图片下载 URL 或 Base64 数据，URL 有效期为 1 小时。

data.progress number

任务处理进度，100 表示处理完成。

data.state number

任务处理状态。1 表示成功；0 或大于 1 表示处理中；小于 0 表示失败。-7 表示无效图片文件，详见状态码说明。

查询图片消除结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 60 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/visual/inpaint/{task_id}

路径参数

task_id string 必填

创建异步图片消除任务后返回的任务 ID，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见状态码说明。

message string

返回说明。任务失败时可参考此字段或联系客服。

data.task_id string

图片消除任务 ID。如果任务失败，请携带此参数联系客服。

data.created_at string

任务创建时间戳。

data.processed_at string

任务开始处理时间戳。

data.completed_at string

任务完成时间戳。

data.image string

结果图片下载 URL 或 Base64 数据，URL 有效期为 1 小时。

data.progress number

任务处理进度，100 表示处理完成。

data.state number

任务处理状态。1 表示成功；0 或大于 1 表示处理中；小于 0 表示失败。-7 表示无效图片文件，详见状态码说明。

使用规范与限制

接口返回的链接有效期为 1 小时，请及时下载存储。
HTTP status 为 200 表示 HTTP 请求成功，并非图片消除任务处理成功，任务结果请结合 data.state 判断，详见状态码说明。
使用 URL 作为参数传递时，请遵守 URL 编码规范，避免参数解析异常。
您不得利用本服务从事任何违反法律法规或侵犯他人合法权利的行为。
需要标出去除区域才能对目标位置进行去除，标记方式支持 蒙版图 和 矩形框。若使用蒙版图，则蒙版图与原始图大小相同，去除区域为白色，其他区域为黑色；去除区域不应大于图像面积的 50%。

原始图蒙版图结果图
上传图片需符合以下格式、分辨率和大小限制。

格式分辨率大小

jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw 最大 4096x4096 最大20MB

格式	分辨率	大小
jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw	最大 4096x4096	最大20MB

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // 仅在异步轮询结果中存在。
    "processed_at": "1634884056", // 仅在异步轮询结果中存在。
    "completed_at": "1634884056", // 仅在异步轮询结果中存在。
    "image": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/inpaint/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "state": 1 // 仅在异步轮询结果中存在。
  }
}