换装 API 接入说明

1. 概述

唯一业务接口：POST /change_cloth_base64。请求体是 JSON，图片字段传 Base64 字符串（支持纯 Base64，也支持 data:image/...;base64,... Data URL）。

推理耗时较长（通常几十秒到几分钟，服务端最长等待约 300 秒）。请把前端请求超时调到至少 320s，并做好 loading / 进度提示，避免用户误以为卡死。

2. 接口地址

POST https://meida.xiangsilian.com/change_cloth_base64

请求头：

Header	值	说明
`Content-Type`	`application/json`	必填

3. 路由规则

服务端根据传入字段自动选择工作流，前端不需要传 mode：

有 kuzi_img

模特 + 上衣 + 裤子换装（同时需要 cloth_img）

有 cloth_img，无 kuzi_img

模特 + 上衣换装

仅 human_img

单图编辑（如改背景 / 按提示词编辑）

4. 请求参数

字段	类型	必填	说明
`human_img`	string	必填	模特 / 人物图 Base64
`cloth_img`	string	可选	上衣图 Base64；默认 `""`
`kuzi_img`	string	可选	裤子图 Base64；默认 `""`。传了则走上衣+裤子流程
`change_desc`	string	可选	提示词。空字符串或不传时使用工作流默认提示；非空则覆盖

图片格式

推荐直接用 FileReader.readAsDataURL(file) 得到的 Data URL 原样上传。
也可只传纯 Base64（不带 data: 前缀），服务端都能解码。
常见格式：JPEG / PNG / WebP 均可。

5. 响应格式

成功

JSON

{
  "ret": 0,
  "state": 0,
  "msg": "success",
  "data": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/tryon/xxxx.png?..."
}

字段	说明
`ret` / `state`	`0` 表示成功
`msg`	状态文案
`data`	结果图 OSS URL（可直接给 `<img src>` 或下载）

失败

JSON

{
  "ret": -1,
  "state": -1,
  "msg": "错误原因说明"
}

常见 HTTP 状态码：400 参数/解码错误，502/503/504 上游 ComfyUI 异常或超时。

前端建议用 ret === 0 && data 判断业务成功；不要只看 HTTP 200。

6. 调用示例

浏览器：File → Base64 → fetch

JavaScript

const API = 'https://meida.xiangsilian.com/change_cloth_base64';

function fileToDataURL(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

async function changeCloth({ humanFile, clothFile, pantsFile, changeDesc = '' }) {
  const body = {
    human_img: await fileToDataURL(humanFile),
    change_desc: changeDesc,
  };
  if (clothFile) body.cloth_img = await fileToDataURL(clothFile);
  if (pantsFile) body.kuzi_img = await fileToDataURL(pantsFile);

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 320_000); // 320s

  try {
    const resp = await fetch(API, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
      signal: controller.signal,
    });
    const json = await resp.json();
    if (json.ret !== 0 || !json.data) {
      throw new Error(json.msg || '换装失败');
    }
    return json.data; // OSS URL
  } finally {
    clearTimeout(timer);
  }
}

仅传模特（单图编辑）

JSON Body

{
  "human_img": "data:image/jpeg;base64,/9j/4AAQ...",
  "change_desc": "换成白色背景"
}

模特 + 上衣

JSON Body

{
  "human_img": "data:image/jpeg;base64,/9j/4AAQ...",
  "cloth_img": "data:image/png;base64,iVBORw0KGgo...",
  "change_desc": ""
}

模特 + 上衣 + 裤子

JSON Body

{
  "human_img": "data:image/jpeg;base64,/9j/4AAQ...",
  "cloth_img": "data:image/png;base64,iVBORw0KGgo...",
  "kuzi_img": "data:image/png;base64,iVBORw0KGgo...",
  "change_desc": ""
}

curl

bash

curl -X POST 'https://meida.xiangsilian.com/change_cloth_base64' \
  -H 'Content-Type: application/json' \
  --max-time 320 \
  -d '{
    "human_img": "data:image/jpeg;base64,/9j/4AAQ...",
    "cloth_img": "data:image/png;base64,iVBORw0KGgo...",
    "change_desc": ""
  }'

7. 注意事项

超时：请设置 ≥ 320 秒；页面侧建议展示已等待秒数。
Payload 体积：三张图 Base64 后体积约 ×1.33，建议前端先压缩到合理分辨率（如长边 1024~2048）再上传。
CORS：服务端已允许任意 Origin，浏览器可直接跨域调用。
结果 URL：data 为阿里云 OSS 签名链接，可直接展示；长期存储请自行转存。
裤子流程：传 kuzi_img 时务必同时传 cloth_img，否则会解码失败。
联调工具：也可打开 /docs（Swagger）在线试调。

8. 健康检查

GET /health

用于确认服务与 ComfyUI 是否可用：

JSON

{
  "status": "ok",
  "comfyui_active": "http://...",
  "comfyui_primary": { "url": "...", "alive": true },
  "comfyui_backup1": { "url": "...", "alive": false },
  "comfyui_backup2": { "url": "...", "alive": false }
}

status 为 ok 时可正常换装；为 degraded 时上游不可用，业务接口会失败。