Skip to content

商品套图(Mockup) ​

将印花图应用到商品套图模板上,生成服装、杯子等产品效果图。

在编辑器中试用:智能套图。

基本信息 ​

项目值
提交任务POST /image/mockup
查询公开模板GET /image/mockup
所需 Scopemockup 或 *
任务类型异步,返回 taskId;成功时 taskType 为 mockup

templateId 来自公开模板列表,或妙图产品内已有的套图模板 ID。


查询公开模板 ​

路径:GET /image/mockup

参数类型默认值说明
pageNointeger1页码
pageSizeinteger20每页数量(最大 100)
namestring—按模板名称筛选(可选)
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 二选一)"
}

参数说明 ​

参数类型必填说明
requestIdstring否调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回
templateIdinteger是套图模板 ID
printingUrlstring与 map 二选一单张印花图 URL
printingUrlsMapobject与 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。

妙图设计 API Beta