人像美姿库 API

三级分类（场景 · 主体 · 服饰 · 美姿）+ 随机取图 · v1 · 在线

鉴权

所有接口需带 token，缺失或错误返回 401。令牌找我单独要，不要写进前端公开代码。

1. 随机取图 GET /api/random-images

参数	必填	说明
`count`	否	取图数量，默认 4，上限 12
`scene`	否	拍摄场景。组级（`自然户外`）自动命中其下所有叶；叶级（`古巷`）精确命中
`subject`	否	主体：女生 / 男生 / 女童 / 男童 / 老人 / 情侣 / 闺蜜 / 亲子 / 祖孙
`costume`	否	服饰：组级（`汉服`）或叶级（`马面裙`）
`frame`	否	构图：全身 / 七分身 / 半身 / 大头特写
`light`	否	光线天气：雪景 / 雾景 / 黄昏蓝调 / 日出晨光 / 雨夜（可与 scene 叠加）
`pose`	否	美姿动作，组级（`特写表情`）或叶级（`撑伞`），支持多值
`token`	是	见鉴权

同参数多值用逗号分隔，语义为 OR；不同参数之间为 AND。
筛选值可用任意层级：scene=外景类（1 层）/ 自然户外（2 层）/ 公园园林（3 层）/ 草坪（4 层叶）——都自动展开到叶。

GET /api/random-images?count=4&scene=公园园林&subject=女生&costume=诃子裙&token=xxx

{
  "ok": true,
  "items": [
    {
      "id": "img000008",
      "url": "https://pose.mengmubiao.cn/images/2026/10/test08.jpg",
      "name": "竹林女生全身撑伞",
      "scene": "竹林", "subject": "女生", "costume": "诃子裙",
      "frame": "全身", "light": null,
      "pose": ["撑伞", "侧颜"],
      "width": 480, "height": 640, "bytes": 10647, "mime": "image/jpeg"
    }
  ],
  "total": 3, "pool": 3, "count": 4,
  "filters": { "scene": ["公园园林"], "subject": ["女生"] }
}

total = 满足条件的池子大小。池子小于 count 时全返，不报错；total: 0 说明条件太窄。

错误

状态	场景	返回
`401`	token 缺/错	`{"error":"unauthorized"}`
`400`	筛选值不在字典	`{"error":"invalid filter","value":"湖岸亭台","kind":"scene","valid":[67个合法值]}` 直接把 valid 给前端做提示，避免静默 0 张

2. 分类字典 GET /api/taxonomy

前端三级联动取树。参数 kind 可选：scene / subject / costume / frame / pose / light，不传返回全部。

GET /api/taxonomy?kind=scene&token=xxx

{ "ok": true,
  "tree": { "scene": [
    { "id": 152, "parent_id": null, "name": "外景类",   "path": "外景类" },
    { "id": 179, "parent_id": 152,  "name": "自然户外", "path": "外景类/自然户外" },
    { "id": 223, "parent_id": 179,  "name": "公园园林", "path": "外景类/自然户外/公园园林" },
    { "id": 267,"parent_id": 223,  "name": "草坪",     "path": "外景类/自然户外/公园园林/草坪" }
  ] } }

用 parent_id 拼树，或用 path 的 / 层级切分渲染多级。

字典规模 158 节点 = 135 叶 + 23 组

kind	节点	说明
scene	69	外景类 → 城市人文/自然户外 → 老街古镇/公园园林… 最深 4 层
costume	41	国风古装 → 汉服 → 先秦两汉/魏晋/唐风/宋制/明制最深 4 层
pose	30	静态站姿 / 坐姿 / 动态氛围 / 特写表情，多对多挂图
subject	9	女生男生女童男童老人情侣闺蜜亲子祖孙
frame	4	全身七分身半身大头特写
light	5	从场景拆出的光线天气维度，可与 scene 叠加筛选

约定

· 图片以 URL 返回，从不 base64，直接 <img src>。
· 返回带 Cache-Control，图目录静态直出 30 天缓存。
· 随机为真随机（应用层洗牌，非 ORDER BY RAND()），同参数连取结果不同。
· 只读接口，无写入端点。