Cabinet · API 调用文档

REQUEST

分析请求体

两个分析接口共用 WardrobeAnalysisRequest。JSON 顶层字段如下。

字段	必须	说明
`user_id`	required	调用方用户标识。前端 Demo 会写成 `wardrobe:{id}` 或 `clone:{user_id}`。
`wardrobe` / `cloth_items`	required（至少一个单品）	同一列表的两个别名，传其中一个即可。空列表会在分析时被拒绝。
`language`	可选	默认 `zh-CN`，也可传 `en-US`。
`analysis_mode`	可选	默认 `wardrobe`（衣橱视角，不读取画像）；显式传 `user` 启用用户画像。两种模式均生成 L2-detail。
`user_profile` / `user_info`	可选	仅用户视角使用，衣橱视角忽略。
`task_id`	可选	不传则服务端生成 `cabinet-…`。

CLOTH ITEMS / WARDROBE

每个单品必须传什么

列表里每一项都会归一成 Cabinet 的 WardrobeItem。校验会同时接受 virtual_try_on 和 Sibyl/Prism 两套字段名。

字段	别名	必须	说明
`item_id`	`id` · `cloth_id`	required	稳定单品 ID。三选一即可，缺这个无法入库。
`category`	`category_id`	强烈建议	点分品类路径，例如 `tops.shirts`、`bottoms.pants`。L1 靠它识别 tops/bottoms/dresses。
`description`	`desc`	强烈建议	自由文本描述，属性推断主要读它。
`name`	—	建议	单品名。缺省为空字符串。
`id_type`	—	可选	默认 `cloth`。虚拟衣橱单品一般是 `item`。
`color`	—	建议	颜色名。有则 L1 颜色分布更准。
`brand`	—	可选	品牌。
`image_url`	—	可选	图片地址。当前分析不读图，前端预览会用。
`attributes`	—	可选	调用方已有的结构化属性，原样保留来源。
`created_at` / `updated_at`	—	可选	ISO 8601 时间。

真正 required 的只有稳定 ID。 没有 item_id / id / cloth_id 会 422。没有品类或描述能过校验，但 L1/L2 几乎推不出有用结构。

SHAPES

两种都能过的衣橱形状

virtual_try_on · `cloth_items`

{
  "user_id": "user-1",
  "language": "zh-CN",
  "cloth_items": [
    {
      "id": "cloth-1",
      "id_type": "cloth",
      "name": "白色宽松衬衫",
      "category_id": "tops.shirts",
      "desc": "棉质，宽松廓形",
      "color": "白色"
    }
  ]
}

Sibyl / Prism · `wardrobe`

{
  "user_id": "user-1",
  "language": "zh-CN",
  "wardrobe": [
    {
      "cloth_id": "cloth-2",
      "name": "黑色直筒裤",
      "category": "bottoms.pants",
      "description": "深色直筒西裤"
    }
  ]
}

异步任务

curl -s -X POST http://127.0.0.1:18731/api/analyze \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"user-1","wardrobe":[{"item_id":"c1","name":"白衬衫","category":"tops.shirts"}]}'

curl -s http://127.0.0.1:18731/api/tasks/{task_id}

任务接口返回 task_id / status / l2x（用户视角）/ wardrobe_style（衣橱视角）/ l2_detail（两种视角均产出）/ error。运行中或失败时摘要字段为 null。完整结果走流式接口。

流式分析

curl -N -X POST http://127.0.0.1:18731/api/analyze/stream \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"user-1","cloth_items":[{"id":"c1","category_id":"tops.shirts","desc":"棉质白衬衫"}]}'

响应是 application/x-ndjson。每行一个事件：stage → stage_done → result；失败时 type=error。

L2-detail · 搭配规划资产摘要

完整结果中的 inferred_profile.l2_detail 按整体轮廓、色彩、材质、版型与设计单品、叠穿、鞋包配饰、搭配方向组织。中文软目标 1500–2500 字。读取所有单品及描述，包含无风格标签衣物和鞋包配饰，不从风格总览扩写。

细节整理按最多 30 组证据或约 18,000 字符分批，单条超长证据独占批次且不截断。流式阶段新增 detail_inventory_1…N → l2_detail。下游可直接使用 injection_sections 中 block=l2_detail 的 standard；规划后仍需检索并验证具体单品组合。

ENDPOINTS

全部接口

方法	路径	说明
GET	`/docs`	本页。机器可读 schema 在 /api/docs。
GET	`/api/health`	进程存活。
GET	`/api/health/llm`	直连 LLM 是否已配置 key。
GET	`/api/config`	公开运行配置；不含密钥。
GET	`/api/users/eligible`	eval 虚拟衣橱、clone 用户，以及 `clothing_model` 正式衣橱。Query：`minimum_valid_items`（默认 30）、`limit`（默认 200）。
GET	`/api/wardrobe/{user_id}`	按 clone user 只读装载衣橱。
GET	`/api/wardrobe/virtual/{wardrobe_id}`	按虚拟衣橱 ID 只读装载。
GET	`/api/wardrobe/model/{wardrobe_id}`	按 `clothing_model` 衣橱 ID 只读装载。
POST	`/api/analyze`	提交分析任务，立即返回 `{ "task_id" }`。
GET	`/api/tasks/{task_id}`	轮询任务：`running` / `success` / `failed`。
POST	`/api/analyze/stream`	流式分析，最后一行 `result.data.analysis` 是完整结果。

衣橱读取接口依赖数据库。未配置 db.pg 时返回 503。分析结果只在响应里返回，不写库。

怎么调 Cabinet。