主题
局部替换(Local Replace)
在图片中识别指定内容,并将其替换为新的内容。适用于产品换色、场景元素替换等场景。
在编辑器中试用:局部替换。
基本信息
| 项目 | 值 |
|---|---|
| 接口路径 | POST /image/local-replace |
| 所需 Scope | local_replace 或 * |
| 任务类型 | 异步,返回 taskId |
请求参数
json
{
"requestId": "可选,调用方自定义唯一 ID",
"url": "原图的公开 HTTPS URL(必填)",
"contentName": "要替换的原始内容名称(必填)",
"newContentName": "替换后的新内容名称(必填)",
"meta": "可选的补充说明"
}参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestId | string | 否 | 调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回 |
url | string | 是 | 原图的公开 HTTPS URL |
contentName | string | 是 | 图片中需要被替换的内容描述,如 "红色连衣裙" |
newContentName | string | 是 | 替换后的目标内容描述,如 "蓝色牛仔裤" |
meta | string | 否 | 调用方可附带的描述。出图提示只用 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。
