主题
商品套图(Mockup)
将印花图应用到商品套图模板上,生成服装、杯子等产品效果图。
在编辑器中试用:智能套图。
基本信息
| 项目 | 值 |
|---|---|
| 提交任务 | POST /image/mockup |
| 查询公开模板 | GET /image/mockup |
| 所需 Scope | mockup 或 * |
| 任务类型 | 异步,返回 taskId;成功时 taskType 为 mockup |
templateId 来自公开模板列表,或妙图产品内已有的套图模板 ID。
查询公开模板
路径:GET /image/mockup
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pageNo | integer | 1 | 页码 |
pageSize | integer | 20 | 每页数量(最大 100) |
name | string | — | 按模板名称筛选(可选) |
bash
curl -s \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
"https://magiqsight.com/openapi/v1/image/mockup?pageNo=1&pageSize=20"json
{
"code": 0,
"data": {
"total": 12,
"list": [
{
"id": 123,
"name": "短袖正面",
"preview": "https://img.magiqsight.com/..."
}
]
}
}查询模板不消耗积分。
提交套图任务
json
{
"requestId": "可选,调用方自定义唯一 ID",
"templateId": 123,
"printingUrl": "单张印花图 URL(与 printingUrlsMap 二选一)"
}参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestId | string | 否 | 调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回 |
templateId | integer | 是 | 套图模板 ID |
printingUrl | string | 与 map 二选一 | 单张印花图 URL |
printingUrlsMap | object | 与 url 二选一 | 带标签的多印花 URL,如 {"印花 A":"https://..."} |
printingUrl 与 printingUrlsMap 必须提供其中一个,且不能同时提供。本地印花先 POST /images/upload,把返回的 data.url 填进 printingUrl 或 printingUrlsMap。
请求示例
bash
curl -s -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"templateId": 123,
"printingUrl": "https://example.com/print.png"
}' \
"https://magiqsight.com/openapi/v1/image/mockup"响应示例
json
{
"code": 0,
"data": {
"requestId": "req_abc123",
"taskId": "task_xyz"
},
"msg": ""
}获得 taskId 后,通过 GET /tasks/{taskId} 轮询结果。
任务成功(status: 1)后,resultType 为 image,结果在 imageUrls。任务失败(status: 2)时,原因在 resultMetadata。
