客户开放 API 接入指南

能力概览

本指南面向需要集成度裁开放 API的客户。您可通过统一的 HTTP 接口完成商家入驻、尺码与商品准备、智能荐码、拍照量体、下单前适配检验与 AI 试穿等能力。 生成与建模细节由平台托管，客户只需按本文约定传参与处理响应。

前提条件

1. 通过 POST /merchant/register 完成商家注册，或由平台为您开通商家账号。
2. 妥善保存响应中的 api_key（仅返回一次）。后续请求在 Header 中携带该 Key。
3. 商家状态为 approved 或 verified 后，方可调用业务接口（荐码、尺码表、量体、试穿等）。待审核（pending）仅可查询入驻信息。
4. 调用接口时，将本文中的 Base URL 替换为平台下发的环境地址。

业务接口统一前缀：/api/v1。探活：GET /health（无业务前缀）。

通用约定

鉴权

终端用户身份

涉及 C 端用户的接口，须同时传递渠道身份（Query 或 Body，与接口约定一致）：

统一错误体

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "缺少 X-Merchant-Api-Key",
    "details": {}
  },
  "request_id": "uuid-or-client-id"
}

商家入驻

注册商家

发送 POST 请求完成入驻，获取 merchant_id 与 api_key。

入参描述

出参描述

请求示例

curl --location '{Base URL}/api/v1/merchant/register' \
--header 'Content-Type: application/json' \
--data '{
  "shop_name": "示例旗舰店",
  "channel": "taobao",
  "contact": "ops@example.com"
}'

响应示例

{
  "merchant_id": "t_xxxx",
  "shop_name": "示例旗舰店",
  "channel": "taobao",
  "status": "pending",
  "api_key": "mk_xxxx",
  "api_key_note": "请妥善保存，服务端仅存哈希"
}

查询当前商家 / 入驻清单

待审核状态亦可调用。清单项通常包括：尺码表、商品绑定、尺码映射推送等。清单齐备后可调用 POST /merchant/onboarding/submit 提交验收。

尺码表与商品

荐码依赖商家尺码表。请先上传尺码表，再将商品绑定到对应 size_chart_id。

上传 / 更新尺码表

入参描述

请求示例

curl --location '{Base URL}/api/v1/merchant/size-charts' \
--header 'Content-Type: application/json' \
--header 'X-Merchant-Api-Key: mk_xxxx' \
--data '{
  "product_id": "pants_001",
  "chart_id": "chart_demo_pants",
  "category": "pants",
  "size_chart": [
    { "size": "M", "waist_girth": [70, 74], "hip_girth": [94, 98], "inside_leg_height": [73, 75] },
    { "size": "L", "waist_girth": [74, 78], "hip_girth": [98, 102], "inside_leg_height": [74, 76] }
  ]
}'

绑定商品

列表查询：GET /merchant/size-charts、GET /merchant/products。

智能荐码

根据用户体征与尺码表进行规则荐码，返回主推尺码、备选尺码与置信度分流建议。

入参描述

出参描述

请求示例

curl --location '{Base URL}/api/v1/size/recommend' \
--header 'Content-Type: application/json' \
--header 'X-Merchant-Api-Key: mk_xxxx' \
--data '{
  "stature": 165,
  "body_mass_kg": 52,
  "gender": "female",
  "waist_girth": 72,
  "hip_girth": 96,
  "product_id": "pants_001"
}'

体征估计（可选）

若需单独估计围度，可先调用：

入参含 stature（必填）、body_mass_kg、gender 及可选自填围度；出参返回估计腰臀胸肩等围度与置信度。

下单前检验

将用户所选尺码与荐码结果比对，返回通过 / 软警告 / 硬警告 / 阻断等级，供下单页决策。

入参描述

出参描述

量体与人体模型

拍照量体采用会话化调用：先创建会话，再按步骤完成量体、生成模型、保存模型，最后基于会话荐码或做下单前检验。 适合嵌入 H5 / 小程序量体组件。

推荐调用顺序

1. POST /fitting/session — 创建会话
2. POST .../suggest-gender（可选）— 正面照性别建议
3. POST .../measure/start — 上传三视图并开始量体
4. POST .../model/generate — 生成预览模型
5. POST .../model/correct（可选）— 微调后重生成
6. POST .../model/save — 固化人体模型，取得 body_model_id
7. POST .../recommend / .../pre-order-check — 会话内荐码与检验

创建量体会话

入参描述

出参描述

开始量体

Content-Type：multipart/form-data

会话内荐码 / 检验

基于会话当前量体与上下文尺码表执行，字段语义与独立荐码 / 检验接口一致。

AI 试穿

AI 试穿为异步接口，调用分为两步：

1. 创建任务：提交试穿请求，获取唯一 task_id。
2. 查询结果：使用 task_id 轮询任务状态，直至完成并获取效果图 URL。

步骤 1：创建任务

入参描述

出参描述

请求示例

curl --location '{Base URL}/api/v1/fitting/tryon' \
--header 'Content-Type: application/json' \
--header 'X-Merchant-Api-Key: mk_xxxx' \
--data '{
  "product_id": "prod_demo_pants",
  "person_image_url": "https://example.com/person.jpg",
  "garment_image_url": "https://example.com/flatlay.jpg",
  "channel": "platform_wechat",
  "channel_user_ref": "oXXXX"
}'

响应示例

{
  "task_id": "ttask_xxxx",
  "status": "pending",
  "image_url": null,
  "message": "试穿任务已提交",
  "estimated_seconds": 30
}

步骤 2：查询结果

建议每隔 2～3 秒调用 GET /fitting/tryon/{task_id}，直至 completed 或 failed。后台对阿里仍为 processing 的任务只刷新 last_poll_at，失败才累加 retry_count（上限 8，另有 120 分钟时间窗）。

curl --location '{Base URL}/api/v1/fitting/tryon/ttask_xxxx?channel=platform_wechat&channel_user_ref=oXXXX' \
--header 'X-Merchant-Api-Key: mk_xxxx'

输入图片要求

高质量输入是高质量输出的前提。人像与服饰图须为公网可访问的 HTTP/HTTPS URL。

人像图

• 文件大小 5KB～5MB；边长 150～4096px；JPG / JPEG / PNG / BMP / HEIC
• 全身正面、光照良好；画面中有且仅有一人；手部尽量完整
• 避免侧身、坐姿、半身、过暗或模糊照片

服饰图

• 尺寸与格式要求同上
• 建议平铺、单件、背景干净、少褶皱；主体占比宜大
• 可通过 POST /fitting/catalog/items/{product_id}/images 维护商品图（如 main / flatlay）

历史记录：GET /fitting/tryon/records（需携带渠道身份）。

错误码

相关文档与联调