Skip to content

局部替换(Local Replace) ​

在图片中识别指定内容,并将其替换为新的内容。适用于产品换色、场景元素替换等场景。

在编辑器中试用:局部替换。

基本信息 ​

项目值
接口路径POST /image/local-replace
所需 Scopelocal_replace 或 *
任务类型异步,返回 taskId

请求参数 ​

json
{
  "requestId": "可选,调用方自定义唯一 ID",
  "url": "原图的公开 HTTPS URL(必填)",
  "contentName": "要替换的原始内容名称(必填)",
  "newContentName": "替换后的新内容名称(必填)",
  "meta": "可选的补充说明"
}

参数说明 ​

参数类型必填说明
requestIdstring否调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回
urlstring是原图的公开 HTTPS URL
contentNamestring是图片中需要被替换的内容描述,如 "红色连衣裙"
newContentNamestring是替换后的目标内容描述,如 "蓝色牛仔裤"
metastring否调用方可附带的描述。出图提示只用 contentName 和 newContentName

本地图片先 POST /images/upload,把返回的 data.url 作为 url。


请求示例 ​

替换服装颜色:

bash
curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/model.jpg",
    "contentName": "红色连衣裙",
    "newContentName": "黑色连衣裙"
  }' \
  "https://magiqsight.com/openapi/v1/image/local-replace"

替换场景元素(附带 meta):

bash
curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/room.jpg",
    "contentName": "木质地板",
    "newContentName": "大理石地板",
    "meta": "保持室内灯光和阴影不变"
  }' \
  "https://magiqsight.com/openapi/v1/image/local-replace"

响应示例 ​

json
{
  "code": 0,
  "data": {
    "requestId": "req_abc123",
    "taskId": "task_xyz"
  },
  "msg": ""
}

获得 taskId 后,通过 GET /tasks/{taskId} 轮询结果。

任务成功(status: 1)后,resultType 为 image,结果在 imageUrls。任务失败(status: 2)时,原因在 resultMetadata。

妙图设计 API Beta