水镜Shuifit
下载 App

开发者

接入水镜个人试穿服务

通过标准 HTTP 接口，让受信任的本地工具或服务端 Agent 提交试穿、查询进度并下载结果。

更新于 2026 年 9 月 8 日

1. 读取接口说明

下载 OpenAPI 3.0 接口描述，获取字段、认证要求、响应格式和当前单次额度。此接入沿用现有账户接口；当前不提供 MCP、A2A 服务或独立 OAuth 授权。浏览器跨域客户端仅允许现有受信任来源，第三方集成请使用服务端或本地客户端。

2. 在受信任的客户端完成认证

认证由用户控制的受信任客户端完成，再通过密钥存储向执行环境注入会话令牌。后续请求使用 Authorization: Bearer <token>。当前会话有效期为 30 天，以登录返回的 expiresAt 为准。OpenAPI 不提供密码登录工具，Agent 不应索要或处理用户密码。

令牌不要放入对话、URL 或日志，只发送到 https://www.shuifit.com。下载时不要将认证头转发到其他域名。当前令牌具有账户级权限，不是仅能试穿的独立密钥；仅适用于用户控制的受信任客户端，不适合向第三方托管 Agent 分发。401 表示需要重新认证。

3. 确认图片与本次额度

先读取 GET /api/mobile/credits，并向用户说明本次需要上传的图片和费用。当前 quality 个人试穿为 1 点/次；最新值见 OpenAPI 的 x-shuifit-tryon.costCredits，人民币价格以套餐页为准。队列任务会占用可用额度，余额查询不等于最终可提交额度。

提交一张人物图和一张衣物图，使用 multipart/form-data。modelImage 和 garmentImage 为图片文件，支持 JPEG、PNG、WebP，每张最大 10 MB；tryOnMode 固定为 quality。garmentRole 可为 top、bottom 或 dress。用户须拥有图片使用权和人物授权。

4. 提交一次并查询进度

POST /api/mobile/tryon/async 返回 202、generationId、cost 和 remainingCredits。接受任务时预留额度，生成成功后扣点；审核不通过或生成失败不完成扣点。402 表示可用额度不足。

保存 generationId，每 5 秒查询 GET /api/mobile/generations/{generationId}/status，遇到临时错误逐步延长间隔。queued、processing 表示等待中；succeeded、failed 为终态。提交接口没有幂等保证；网络超时或响应丢失时，不要自动重复 POST，可先查看 GET /api/mobile/generations 的近期记录并确认。

5. 下载结果

任务成功后，携带相同 Bearer 令牌请求 GET /api/mobile/generations/{generationId}/image，得到 JPEG 文件。只能读取当前账户有权访问的记录。图片保留 30 天；不存在、过期或不可用的结果返回 404。生成结果仅供服装展示与试穿参考，不保证实际尺码或穿着效果。

接口文件与调用示例

下载 OpenAPI JSON · 读取机器可读网站说明

# Token is supplied by a trusted local client or secret store.
# Run once only, after the user approves image upload and credit spending.
curl https://www.shuifit.com/api/mobile/tryon/async \
  -H "Authorization: Bearer $SHUIFIT_TOKEN" \
  -F "modelImage=@person.jpg;type=image/jpeg" \
  -F "garmentImage=@garment.jpg;type=image/jpeg" \
  -F "tryOnMode=quality" \
  -F "garmentRole=top"

# Save generationId from the 202 response; poll with backoff.
curl "https://www.shuifit.com/api/mobile/generations/$GENERATION_ID/status" \
  -H "Authorization: Bearer $SHUIFIT_TOKEN"

# Only after status=succeeded:
curl "https://www.shuifit.com/api/mobile/generations/$GENERATION_ID/image" \
  -H "Authorization: Bearer $SHUIFIT_TOKEN" -o result.jpg

了解产品 · 查看套餐 · 隐私政策 · 接入问题反馈