开发者 API

一次 API 调用，完成虚拟试穿。

上传一张人物照和一张服装图，即可拿回以假乱真的试穿效果。一个接口、一把密钥、按积分计费。

curl

curl -X POST https://tryonanytime.com/api/v1/tryon \
  -H "Authorization: Bearer sk_your_key" \
  -F "person=@me.jpg" \
  -F "garment=@dress.jpg" \
  -F "prompt=keep my face and pose"

三步快速上手

从零到第一次试穿，五分钟搞定。

01
创建 API 密钥
登录后在 API 密钥页面生成一把 sk_ 密钥。密钥会被保存下来，之后可随时再次复制；配置 CONFIG_ENCRYPTION_KEY 时加密存储，未配置则为明文，生产环境务必配置。
02
发起第一次试穿
向 /api/v1/tryon 发起 POST 请求，提交人物图和服装图——支持 multipart 上传，也可以用 JSON 传可公开访问的图片 URL。
03
拉取结果
轮询任务状态接口，直到 status 变为 succeeded，再从 result_url 下载图片。

身份验证

每个请求都要在 Authorization 头里带上你的密钥。密钥以 sk_ 开头，扣的是你账户里的积分。

随时可以在 /settings/apikeys 创建和吊销密钥。
密钥以加密形式存储在服务端（配置 CONFIG_ENCRYPTION_KEY 时为 AES-256-GCM 加密，否则为明文存储），创建后可随时在密钥列表中再次复制。生产环境务必配置 CONFIG_ENCRYPTION_KEY。
不要把 sk_ 密钥写进前端代码，请从你自己的服务器调用 API。

管理 API 密钥

请求头

Authorization: Bearer sk_your_key

接口参考

试穿能力的全部接口。所有 JSON 响应都使用同一套 code、message、data 信封。

POST/api/v1/tryon

创建一次试穿任务。可以用 multipart 直接上传图片文件，也可以用 JSON 传可公开访问的图片 URL。

请求

multipart/form-data
  person      <file>   photo of the person
  garment     <file>   the garment image
  garment_url string   https URL of the garment (instead of garment)
  prompt?     string   optional styling hint

or application/json
  { "person_url": "https://…",
    "garment_url": "https://…",
    "prompt": "…" }  // prompt optional

响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "succeeded",
    "result_url": "/api/v1/tryon/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/result",
    "demo": false
  }
}

GET/api/v1/tryon/{id}

查询试穿任务状态。轮询直到 status 变为 succeeded，然后使用 result_url。

响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "succeeded",
    "result_url": "/api/v1/tryon/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/result",
    "created_at": "2025-01-01T12:00:00Z"
  }
}

GET/api/v1/tryon/{id}/result

下载试穿成品图。直接返回图片字节（image/*），不是 JSON 信封。

响应

GET /api/v1/tryon/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/result
Authorization: Bearer sk_your_key

→ 200 OK
  Content-Type: image/png
  <raw image bytes>

GET/api/v1/me

查询密钥对应的账户信息——适合在你自己的界面里展示剩余积分。

响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "email": "you@example.com",
    "credits": 42
  }
}

POST/api/v1/embed/tryon

商家嵌入专用。使用 pk_ 公开密钥，放在 X-Embed-Key 头里；仅接受来自你白名单 Origin 的请求。

请求

POST /api/v1/embed/tryon
X-Embed-Key: pk_your_embed_key
Origin: https://your-store.com   // allow-listed

multipart/form-data only
  person      <file>   photo of the person
  garment_url string   https URL of the garment (or send garment <file>)
  prompt?     string   optional styling hint

响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "succeeded",
    "result_url": "/api/v1/tryon/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/result",
    "demo": false
  }
}

查看嵌入完整指南 →

错误码

错误同样使用统一信封，code 固定为 -1；具体错误标识看 message 字符串（如 invalid_api_key）。

HTTP	含义	处理建议
401`invalid_api_key`	密钥缺失、已吊销或格式错误。	检查 Authorization 头；若密钥泄露，请重新生成一把。
400`invalid_image`	图片无法读取、体积过大或格式不支持。	转成 JPEG、PNG 或 WebP 后重试。
402`insufficient_credits`	账户积分不足。	在定价页充值后，用原参数重试即可。
403`domain_not_allowed`	嵌入请求来自白名单之外的 Origin。	在嵌入设置中添加该域名，或检查 Origin 是否拼写有误。
404`not_found`	任务 ID 不存在，或属于其他密钥。	视为最终结果，不要用同一个 ID 重试。
429`too_many_requests`	触发限流：too_many_requests，或嵌入密钥达到每日积分上限（daily_limit_reached）。	按 Retry-After 的秒数退避后重试；用队列排队任务，不要突发并发。
500`tryon_failed`	请求已受理，但试穿生成或服务端失败（其他接口可能返回 server_error）。	退避后重试；已扣积分会自动退回。
503`unavailable`	试穿服务暂时不可用。	以指数退避重试；若持续出现，请告警并联系我们。

限流说明

合理的限流保证所有人的低延迟。需要更高配额？请联系我们。

按 API 密钥

试穿调用：每个 key owner（密钥所属账户）每 5 秒一次。读取调用（status、result、me）：每个 key owner 每 500 毫秒一次。

按 IP 地址

试穿调用：每个 IP 每 2 秒一次，跨所有密钥合计。读取调用：每个 IP 每 1 秒一次。

代码示例

一次完整流程：创建试穿、轮询到完成、保存图片。把 sk_your_key 换成你的密钥即可直接运行。

curl -X POST https://tryonanytime.com/api/v1/tryon \
  -H "Authorization: Bearer sk_your_key" \
  -F "person=@me.jpg" \
  -F "garment=@dress.jpg" \
  -F "prompt=keep my face and pose"

响应信封

所有 JSON 响应都用同一层包装，成功处理逻辑在各个接口间完全一致。

code: 0 表示成功，-1 表示失败；具体错误标识在 message 字段。
message: 人和机器都能读懂的标识；成功时为 "ok"。
data: 接口的业务数据，结构见上文。

{code, message, data}

{
  "code": 0,         // 0 = success, -1 = failure
  "message": "ok",   // on failure: the specific error id, e.g. "invalid_image"
  "data": { }        // endpoint payload (absent on errors)
}