图片消除笔-高级API

免费体验

上传原图与标记消除区域的 mask 图，消除图片中的指定内容。

接口返回的结果图片链接一般有效期为 1 小时，请及时下载存储。

鉴权

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

X-API-KEY: YOUR_API_KEY

创建高级图片消除任务

POST /api/tasks/visual/external/image-inpainting

请求参数

image_url string 可选

原图下载地址。与 image_file 至少提供一个；同时传入时优先使用 image_file。

二选一必填

image_file file 可选

原图文件（二进制）。与 image_url 至少提供一个；同时传入时优先使用 image_file。

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

mask_url string 可选

用于指定消除区域的 mask 图片下载地址。与 mask_file 二选一必填。

二选一必填

mask_file file 可选

用于指定消除区域的 mask 图片文件（二进制）。与 mask_url 二选一必填。

provider integer 可选

处理路线：

1：路线 1（默认）
2：路线 2

返回参数

status integer

HTTP 响应状态码。200 表示请求成功，不代表图片处理成功。详见状态码说明。

message string

返回的信息说明。处理失败时请携带错误信息和 task_id 联系支持人员。

data.task_id string

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

查询高级图片消除结果

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

GET /api/tasks/visual/external/image-inpainting/{task_id}

路径参数

task_id string 必填

创建图片消除任务后返回的任务 ID。

返回参数

status integer

HTTP 响应状态码。200 表示请求成功，不代表图片处理成功。详见状态码说明。

message string

返回的信息说明。处理失败时请携带错误信息和 task_id 联系支持人员。

data.task_id string

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

data.image string

处理结果图片下载地址或 base64 数据。结果链接一般有效期为 1 小时。

data.state integer

任务状态：0 排队中；1 成功；2 准备中；3 等待中；4 处理中；< 0 失败。成功或失败后均应停止轮询。详见状态码说明。

data.progress integer

任务进度，取值范围 0～100。请结合 data.state 判断处理是否成功。

data.created_at integer

任务创建时间戳。

data.processed_at integer

任务开始处理时间戳。

data.completed_at integer

任务完成时间戳。

data.time_elapsed string

任务处理耗时。

data.state_detail string

任务状态详情。

data.return_type integer

结果返回方式。

data.cost number

接口返回的费用值。

data.use_point integer

本次任务消耗的算粒。每次成功调用消耗 6 算粒。

使用规范与限制

接口返回的结果图片链接一般有效期为 1 小时，请及时下载存储。
HTTP status 为 200 仅表示请求成功；data.state = 1 才表示处理成功，data.state < 0 表示失败。成功或失败后均应停止轮询。
URL 作为参数传递时，请遵守 URL 编码规范。下载结果时请保留完整签名参数，避免将 & 错误转义后导致链接不可用。
原图和 mask 图片均需符合下方格式、大小和分辨率限制。每个下载地址最长 512 个字符，支持 HTTP 和 OSS 协议，下载超时 20 秒。
通常在 1～2 分钟内完成，耗时受图片大小影响，最长处理时间为 10 分钟。
默认 QPS 为 2；如需提高限制，请联系商务。每次成功调用消耗 6 算粒。
原图和 mask 图片均需符合以下要求。

格式大小分辨率

jpg, jpeg, png（建议 JPEG）每张不超过 4.7MB ≤ 4096 × 4096

格式	大小	分辨率
jpg, jpeg, png（建议 JPEG）	每张不超过 4.7MB	≤ 4096 × 4096

响应

{
  "status": 200,
  "data": {
    "task_id": "94806a3f-1173-4afb-9bcc-3ff19c0981f4",
    "created_at": 1789541552,
    "processed_at": 1789541552,
    "completed_at": 1789541563,
    "image": "YOUR_RESULT_IMAGE_URL",
    "progress": 100,
    "state": 1,
    "state_detail": "Complete",
    "return_type": 2,
    "cost": 0,
    "use_point": 6
  }
}