物品高级精修API

免费体验

AI 根据原图与 mask 对指定物品区域进行高级精修，可优化材质、线条和商品细节，并可通过 retain_mask 保留指定区域特征。适用于电商商品图、饰品、箱包、透明物体、金属物体等精修场景。支持异步、同步两种调用方式。

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

鉴权

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

X-API-KEY: YOUR_API_KEY

创建物品精修任务

POST /api/tasks/visual/retouching-collection

请求参数

image_url string 可选

图片下载地址。与 image_file 二选一必填；支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时为 10 秒。如果同时传入 image_file 与 image_url，优先使用 image_file。

二选一必填

image_file file 可选

图片文件（二进制）。与 image_url 二选一必填，优先级高于 image_url。

图片尺寸与分辨率需与原图保持一致，请参看使用规范与限制#4。
图片上传要求请参看使用规范与限制#5。

mask_url string 可选

精修主体的 mask 图下载地址。与 mask_file 二选一必填；支持 HTTP 协议和 OSS 协议，最长 512 个字符，下载超时为 10 秒。如果同时传入 mask_file 与 mask_url，优先使用 mask_file。

二选一必填

mask_file file 可选

精修主体的 mask 图，抠图完的 mask 图（二进制）。与 mask_url 二选一必填，优先级高于 mask_url。

图片尺寸与分辨率需与原图保持一致，请参看使用规范与限制#4。

retain_mask_url string 可选

需要特征保留区域的 mask 图下载地址，最长 512 个字符。与 retain_mask_file 二选一，均为选填；不传则对精修主体全部进行处理。

二选一选填

retain_mask_file file 可选

需要特征保留区域的 mask 图（二进制）。与 retain_mask_url 二选一，均为选填，优先级高于 retain_mask_url；不传则对精修主体全部进行处理。

图片尺寸与分辨率需与原图保持一致，请参看使用规范与限制#4。

sync number 可选

是否等待结果就绪并立即返回。0 表示异步返回 task_id，稍后通过 task_id 获取结果；1 表示同步等待结果并立即返回。

retouch_strength number 可选

材质强度，范围 0-100，默认 37。值越高材质变化越大，仅在普通模型下生效。

line_strength number 可选

线条强度，范围 0-100，默认 60。值越高线条约束越强，仅在普通模型下生效。

type number 可选

精修类型。1 表示普通模型-通用；2 表示高级模型-通用；3 表示高级模型-透明；4 表示高级模型-金属；5 表示高级模型-饰品；6 表示高级模型-箱包。默认 1。

返回参数

status number

HTTP 响应状态码。200 表示 HTTP 请求成功，并不代表物品精修成功，详见状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

异步物品精修任务 ID。创建任务成功后返回，用于后续查询物品精修结果。

status number

HTTP 响应状态码。200 表示 HTTP 请求成功，并不代表物品精修成功，详见状态码说明。

message string

接口返回消息。

data.task_id string

物品精修任务 ID。

data.created_at string

任务创建时间戳。

data.processed_at string

任务开始处理时间戳。

data.completed_at string

任务完成时间戳。

data.image string

物品精修结果图片 URL 或 Base64 数据，链接有效期为 1 小时。

data.return_type number

结果返回方式。

data.type number

本次任务使用的精修类型。

data.progress number

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

data.state number

任务状态码。1 表示完成，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

data.time_elapsed string

耗时。

data.state_detail string

任务状态详情。

查询物品精修结果

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

GET /api/tasks/visual/retouching-collection/{task_id}

路径参数

task_id string 必填

物品精修任务 ID。创建异步任务后返回，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示 HTTP 请求成功，并不代表物品精修成功，详见状态码说明。

message string

接口返回消息。

data.task_id string

物品精修任务 ID。

data.created_at string

任务创建时间戳。

data.processed_at string

任务开始处理时间戳。

data.completed_at string

任务完成时间戳。

data.image string

物品精修结果图片 URL 或 Base64 数据，链接有效期为 1 小时。

data.return_type number

结果返回方式。

data.type number

本次任务使用的精修类型。

data.progress number

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

data.state number

任务状态码。1 表示完成，大于 1 表示处理中，小于 0 表示失败，详见状态码说明。

data.time_elapsed string

耗时。

data.state_detail string

任务状态详情。

使用规范与限制

接口返回的结果图片链接一般有效期为 1 小时，请及时下载并存储。
HTTP status 为 200 表示 HTTP 请求成功，并非物品精修成功，详见状态码说明。
使用 URL 作为参数传递时，请遵守 URL 编码规范，避免参数解析混乱。
输入的 image 图片 与 mask 图片 的尺寸和分辨率必须一致；如果传递了 retain_mask 图片，则三者图片需要保持一致。

原图精修主体 mask 图特征保留区域 mask 图结果图
上传图片需符合以下格式、分辨率和大小限制。

格式分辨率大小

jpg, jpeg, bmp, png, webp, tiff, bitmap 最大 4096x4096 小于30MB

格式	分辨率	大小
jpg, jpeg, bmp, png, webp, tiff, bitmap	最大 4096x4096	小于30MB

响应

{
  "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/retouching-collection/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // 仅在异步轮询结果中存在。
    "return_type": 1, // 仅在异步轮询结果中存在。
    "type": 1, // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "state": 1, // 仅在异步轮询结果中存在。
    "time_elapsed": "4.23s", // 仅在异步轮询结果中存在。
    "state_detail": "success" // 仅在异步轮询结果中存在。
  }
}