feat(接口99): 人脸特殊点检测 + 网关转发路由；文档同步至当前代码

- worker: POST /api/v1/face/special-points，60 个固定编号关键点（6组） + 5 个发际线特殊点（沿指定关键点方向射线步进，与 BiSeNet 头发 mask 首次相交；双射线取中点，left_left=mid(333→332, 298→284) 与右侧镜像） - 网关: 同路径盲转发路由（调用频率低，维持转发不占网关依赖；响应无 *_base64 字段，改写逻辑天然跳过） - 测试页 static/test_interface99.html：分组着色小点 + 点ID标注（可开关） + 发际线点大圆标签 + JSON 展示 - 文档: CLAUDE.md 重写至当前架构；实现说明/接口文档补接口 9~12/99 契约；网关待改动补 §7(9/10已加) §8(11/12待加) §9(接口99部署步骤)
2026-09-06 23:37:01 +08:00
parent 989f4d0d18
commit 63bd265386
8 changed files with 906 additions and 93 deletions
@@ -267,8 +267,10 @@
 | gender | string | **是** | 性别：`male` / `female`。决定使用的发际线贴图集合 |
 | hair_style | string | **是** | 发型序号，**逗号分隔多选**（如 `1,2,3`），最多不超过该性别的预设数。female：1=ellipse, 2=flower, 3=heart, 4=straight, 5=wave, 6=bigflower, 7=clasicalflower；male：1=ellipse, 2=inverse_arc, 3=m, 4=straight, 5=heart, 6=Softpetal, 7=wave。越界/非法返回 `1007` |
 | beauty_enabled | bool | 否 | 生发图是否带美颜效果，默认 false（当前阶段不生效） |
-| use_mask | bool | 否 | 是否启用 inpaint 遮罩，默认 `true`。`false` 时用干净原图生成（空遮罩、不烧模板黑线），供测试对比 |
-| prompt | string | 否 | ComfyUI 提示词，默认「补充遮罩区域的头发，加一点美颜」，会替换工作流节点 60 的文本 |
+| use_mask | bool | 否 | 是否启用 inpaint 遮罩，默认 `true`。`false` 时用干净原图生成（空遮罩、不烧模板黑线），供测试对比。仅对原生发（male / female 6/7）管线生效 |
+| prompt | string | 否 | ComfyUI 提示词，默认「填充遮罩区域的头发」，会替换工作流节点 60 的文本。仅对原生发管线生效（female 1..5 换发型分支的提示词内部固定） |
+| flux_model | string | 否 | Flux 模型文件名（如 `flux-2-klein-9b-Q5_K_M.gguf`）。缺省用工作流默认（9B-Q4_K_M）；`.gguf` 自动切 UnetLoaderGGUF 并同步配套 qwen CLIP |
+| redraw_max_side | int | 否 | female 1..5 重绘管线送模型前的长边上限像素。缺省=服务端默认（`REDRAW_MAX_SIDE`，当前 1024）；`0`=不缩图（原图直送，更慢） |

 ### 输出（data）

@@ -281,7 +283,8 @@
 | hairline_type | string | 发际线类型 key：`ellipse`/`flower`/`heart`/`straight`/`wave`/`bigflower`/`clasicalflower`（female），`ellipse`/`m`/`straight`/`inverse_arc`/`heart`/`Softpetal`/`wave`（male） |
 | order | int | 排序序号（当前阶段固定 `1..N`，按贴图顺序，暂不计算合适度） |

-> ⚠️ 生发图由本机 ComfyUI（Flux-2，端口 8182）生成，**一次请求生成指定发型的 1 张、同步返回**。
+> ⚠️ 生发图由本机 ComfyUI（Flux-2，端口 8188）生成，**一次请求生成指定发型的 1 张、同步返回**；
+> female 1..5 的生发图另依赖 change_hair 换发型服务（:8801）。
 > worker 侧返回 `image_base64` / `grown_image_base64`，
 > 网关落盘后改写为上表的 `image_url` / `grown_image_url`。
 >
@@ -352,7 +355,7 @@

 ## 接口 4：用户特征接口

-**说明**：输入用户照片，由**火山方舟 豆包视觉模型**（`doubao-seed-2-0-lite-260428`）分析，输出一大批面部特征。
+**说明**：输入用户照片，由**火山方舟 豆包视觉模型**（`doubao-seed-1-6-vision`）分析，输出一大批面部特征。

 **请求**：`POST /api/v1/face/features`

@@ -515,16 +518,197 @@

 ---

+## 接口 9：头发遮罩生成接口
+
+**说明**：输入一张含人头的照片，生成头发遮罩，并返回**每一步的可视化图**（供对比调试）。
+
+**请求**：`POST /api/v1/head/mask`
+
+### 输入
+
+图片参数见「通用约定 → 图片传参字段」。专属参数：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| erode_cm | float | 否 | 外缘朝中心（鼻梁 151 点）内缩的距离（厘米），默认 1.2 |
+
+### 处理流程
+
+1. MediaPipe 关键点 → 底部分割线（关键点 21,68,104,69,108,151,337,299,333,298,251 的连线，21 水平延伸到最左、251 延伸到最右）。
+2. 分割线以上为「上半区」。
+3. 头发分割（**BiSeNet** 与 **SegFormer** 两套）；从每列最顶端头发向下填充到分割线，得到**含额头**的闭合区域（头发+额头，不割断）。
+4. 外缘朝中心点 151 内缩 `erode_cm`（虹膜标定换算像素）、底线不动 → 最终遮罩。
+
+### 输出（data）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| px_per_cm | float | 虹膜标定出的像素/厘米 |
+| erode_cm / erode_px | float / int | 内缩距离（厘米 / 像素） |
+| image_size | object | `{width, height}` 原图尺寸 |
+| steps_common | object | `landmarks_baseline_*`（关键点/分割线）、`upper_region_*`（上半区） |
+| bisenet / segformer | object | 两套分割模型各自的结果：`hair_mask_*`（原始头发分割）、`closed_region_*`（含额头闭合区域）、`final_overlay_*`（最终遮罩叠加可视化）、`mask_*`（最终遮罩 PNG）及 `hair_pixels`/`closed_pixels`/`mask_pixels` 像素计数 |
+
+> worker 返回 `*_base64`（data URI），经网关改写为 `*_url`。
+
+---
+
+## 接口 10：头部外缘膨胀带遮罩接口
+
+**说明**：先和接口9 一样得到内缩后的基准遮罩，再沿头部外缘生成一条膨胀带遮罩。
+
+**请求**：`POST /api/v1/head/band`
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| erode_cm | float | 否 | 基准遮罩外缘朝 151 内缩距离（厘米，同接口9），默认 1.2 |
+| dilate_cm | float | 否 | 外轮廓线膨胀后带子总宽（厘米），默认 2.0 |
+
+### 处理流程
+
+1. 取基准遮罩的**外轮廓线**，去掉贴着底部分割线的那一段（只留头发/头部外缘弧线）。
+2. 把外轮廓线膨胀成带子（总宽 `dilate_cm`；半径=总宽/2，虹膜标定换算像素）。
+3. 裁到分割线以上（不越过底线）。
+
+### 输出（data）
+
+结构同接口9，但每组结果为 `base_mask_*`（基准遮罩）/ `contour_*`（外轮廓线）/ `band_overlay_*`（带子叠加可视化）/ `mask_*`（最终带状遮罩）及 `base_pixels`/`band_pixels` 计数，另有 `dilate_cm`/`dilate_radius_px`。
+
+---
+
+## 接口 11：发际线生发接口（不含重绘）
+
+**说明**：输入一张**发际线较高 / 头发稀少**的正脸图 + 发际线类型 ID，输出同一个人、同一发型、按该类型压低发际线后的图片，并返回**每一步可视化**。重绘版见接口12。
+
+**请求**：`POST /api/v1/hairline/grow`
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| hairline_id | string | **是** | 发际线类型 ID（= change_hair `hair_id`）：`chang_tuoyuan` / `chang_huaban` / `chang_xinxing` / `chang_zhixian` / `chang_bolang` |
+| gen_backend | string | 否 | 生成后端：`swaphair`（换发型 LoRA，默认）｜`hairgrow`（区域生发 inpaint） |
+| hairgrow_strength | float | 否 | 区域生发强度（仅 hairgrow 后端），默认 0.75 |
+| is_hr | bool | 否 | 高清模式（换发型输出 1152×1536，否则 576×768），默认 false |
+| seg_model | string | 否 | 头发分割模型：`bisenet` ｜ `segformer`（默认） |
+| erode_cm | float | 否 | baseline 参考内缩距离（厘米），默认 0.6 |
+| hairline_push_cm | float | 否 | 发际线外推距离（厘米，往头发方向推进），默认 1.0 |
+| hairline_edge | string | 否 | 发际线提取方式：`column`（默认）｜`contour` |
+| swap_mode | string | 否 | 换发型取图模式：`ext_mask`（默认，把接口9 遮罩传给 webui 精确重绘）｜`as_is`（用内部遮罩，贴回时再裁） |
+| edge_erode_px | int | 否 | 贴图前遮罩内缩像素（防边缘露皮/光晕），默认 3 |
+| denoising_strength | float | 否 | 换发型 webui 重绘强度（越大生发越激进），默认 0.6 |
+| mb_levels | int | 否 | 多频段金字塔层数（2~6），默认 5 |
+| blend_method | string | 否 | 接缝融合：`multiband`（默认）｜`seamless`（泊松）｜`two_stage`（泊松→多频段）｜`feather`（高斯羽化）｜`alpha_gradient`（距离渐变） |
+| color_match | bool | 否 | 融合前 Reinhard 颜色迁移消除整体色差，默认 true |
+| color_match_strength | float | 否 | 颜色迁移强度（0~1），默认 1.0 |
+| mb_feather_px | int | 否 | 多频段最细层掩码轻羽化像素，默认 1 |
+| transition_band_px | int | 否 | keep-region 过渡带边距（-1=自动按层数 2^n），默认 -1 |
+| inpainting_fill | int | 否 | change_hair 服务端重绘填充：0=保留原图 ｜ 1=噪声（默认）｜ 2=纯色 ｜ 3=潜变量噪声 |
+| mask_blur | int | 否 | change_hair 服务端遮罩边缘模糊像素，默认 11 |
+| mask_dilate_scale | float | 否 | change_hair 服务端遮罩膨胀缩放（<1 收缩防越界），默认 1.0 |
+
+### 输出（data）
+
+`steps`：`input`（原图）/ `baseline`（底部分割线）/ `hair_mask`（头发分割）/ `mask_overlay`（遮罩叠加）/ `mask`（遮罩）/ `swap_raw`（换发型原始输出）/ `alpha`（融合权重）/ `final`（最终结果）各步图（`*_base64`，经网关改写为 `*_url`），另有 `timings_ms` 分步耗时。
+
+> ⚠️ `swaphair` 后端依赖 change_hair（:8801）在跑；`hairgrow` 后端依赖 ComfyUI（:8188）。
+
+---
+
+## 接口 12：发际线带重绘接口
+
+**说明**：接口11 的**下游重绘阶段**——内部先跑接口11 核心管线拿 ④ 接缝融合最终图（final），再取发际线重绘带（外推 `band_lo_mult×push` ~ `band_hi_mult×push` 之间、经 baseline 截断只留上部的带状区域）作遮罩，用 **Flux-2（ComfyUI，reference-latent 保色重绘）** 重绘。
+
+**同时产出两版结果**：
+
+- `redraw_full`：ComfyUI 整帧输出（全脸美颜 + 全脸重绘）。
+- `redraw_band`：加发只在发际线带内、band 外保留 final 结构并按 `beauty_alpha` 融入全脸美颜。
+
+**请求**：`POST /api/v1/hairline/grow_v2`
+
+### 输入
+
+接口11 的全部参数（见上表）再叠加：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| comfyui_prompt | string | 否 | Flux-2 重绘提示词，缺省「填充遮罩区域的头发」 |
+| beauty_alpha | float | 否 | redraw_band 版 band 外的全脸美颜融入强度（0=band 外纯用 final，1≈整帧版），默认 0.6 |
+| band_lo_mult | float | 否 | 重绘带外推倍率下限（相对 hairline_push_cm），默认 0.5 |
+| band_hi_mult | float | 否 | 重绘带外推倍率上限（相对 hairline_push_cm），默认 1.5 |
+
+### 输出（data）
+
+`steps`：`input` / `final`（重绘输入基底）/ `redraw_band_overlay`（重绘带可视化）/ `redraw_full`（A 整帧）/ `redraw_band`（B 局部+美颜）/ `redraw_c`（兼容旧字段，=redraw_full）；重绘异常在 `redraw.c_error` 报告。
+
+### 精简变体（生产推荐）
+
+| 路径 | 说明 |
+|------|------|
+| `POST /api/v1/hairline/grow_v2_final` | 仅需图片 + `hairline_id`，其余参数固化为调优默认值（push=0.8cm / two_stage / color_match=关 等），**最终取整帧重绘 `redraw_full`** |
+| `POST /api/v1/hairline/grow_v2_final_v2` | 参数同上，**最终取 B 局部加发+全脸美颜 `redraw_band`** |
+
+> ⚠️ 依赖 ComfyUI（:8188）与 change_hair（:8801）均在跑。接口2 女性 1..5 的生发图即复用 `grow_v2_final` 管线。
+
+---
+
+## 接口 99：人脸特殊点检测接口
+
+**说明**：输入一张人脸照片，返回一组**固定编号 MediaPipe Face Mesh 关键点**的像素坐标，外加 5 个**发际线特殊点**（射线与头发分割发际线的交点）。
+
+**请求**：`POST /api/v1/face/special-points`
+
+### 输入
+
+图片参数见「通用约定 → 图片传参字段」，无专属参数。要求单人正面照（非正面返回 `1003`）。
+
+### 输出（data）
+
+`points`：字段名 = `<组英文名>_<点ID>`，值为原图像素坐标 `{x, y}`（int）；发际线点不可得（秃顶/分割失败）时为 null。
+
+| 组 | 字段前缀 | 点 ID |
+|----|----------|-------|
+| 眉毛 | `eyebrow` | 107 66 105 63 70 336 296 334 293 300 |
+| 眼睛 | `eye` | 189 222 224 113 226 413 442 444 342 446 |
+| 嘴 | `mouth` | 0 37 40 67 91 84 17 405 375 409 269 |
+| 中线鼻 | `nose_midline` | 9 168 197 5 4 194 278 48 437 217 |
+| 面颊 | `cheek` | 101 117 123 187 205 50 330 346 352 280 425 |
+| 边线 | `face_edge` | 162 234 58 136 149 152 378 365 288 401 366 389 251 |
+
+**发际线特殊点**（沿关键点 a→b 方向射线步进，首次进入 BiSeNet 头发 mask 处为交点；双射线取中点，仅一条命中返回该点）：
+
+| 字段 | 计算 |
+|------|------|
+| `hair_line_center` | 151→10 方向交点 |
+| `hair_line_right` | mid(108→109 交点A, 69→67 交点B) |
+| `hair_line_right_right` | mid(104→103 交点A, 68→54 交点B) |
+| `hair_line_left` | mid(337→338 交点A, 299→297 交点B) |
+| `hair_line_left_left` | mid(333→332 交点A, 298→284 交点B) |
+
+另有 `image_size`（宽高）与 `hairline_source`（`segmentation`=发际线点已算出 / `unavailable`=分割不可用，发际线点为 null）。
+
+---
+
 ## 汇总：输入输出一览

-| 接口 | 输入 | 主要输出 |
-|------|------|----------|
-| 1 四庭七眼测量 | 用户照片 | 标注 PNG（无人物）+ 四庭/七眼厘米数值与坐标 |
-| 6 四庭七眼测量 v2 | 用户照片 | 同接口1，复刻实现 |
-| 2 C 端生发 | 用户照片 | 生发后图片 + 指定发际线预览（单/多张） |
-| 3 B 端生发 | 划线图片 | 最合适发际线图片 + 生发后图片 |
-| 4 用户特征 | 用户照片 | 6 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格） |
-| 5 发际线 PNG | 用户照片 + gender + hair_style（多选） | 每个选中发型 middle/high/low 三档发际线叠图 + 生发图 + 最合适发际线面部中间点坐标 |
+| 接口 | 路径 | 输入 | 主要输出 |
+|------|------|------|----------|
+| 1 四庭七眼测量 | `/api/v1/face/measure` | 用户照片 | 标注 PNG（无人物）+ 四庭/七眼厘米数值与坐标 |
+| 6 四庭七眼测量 v2 | `/api/v1/face/measure-v2` | 用户照片 | 同接口1，去顶庭变体 |
+| 2 C 端生发 | `/api/v1/hair/grow` | 用户照片 + gender + hair_style（多选） | 每发型预览 PNG + 生发图（female 1..5=换发型+重绘，其余=原生生发） |
+| 7 C 端生发 v2 | `/api/v1/hair/grow-v2` | 同接口2 | 同接口2（add_hair2 工作流，已弃用隐藏） |
+| 3 B 端生发 | `/api/v1/hair/grow-b` | 划线图片 | 检测到的发际线 + 生发后图片 |
+| 4 用户特征 | `/api/v1/face/features` | 用户照片 | 6 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格），网关本机实现 |
+| 5 发际线 PNG | `/api/v1/hairline/generate` | 用户照片 + gender + hair_style（多选） | 每个选中发型 middle/high/low 三档发际线叠图 + 生发图 + 最合适发际线面部中间点坐标 |
+| 9 头发遮罩 | `/api/v1/head/mask` | 用户照片 | 头发遮罩 + 分步可视化（BiSeNet/SegFormer 双路） |
+| 10 外缘膨胀带 | `/api/v1/head/band` | 用户照片 | 头部外缘带状遮罩 + 分步可视化 |
+| 11 发际线生发 | `/api/v1/hairline/grow` | 用户照片 + hairline_id | 压低发际线图 + 全步骤可视化（不含重绘） |
+| 12 发际线带重绘 | `/api/v1/hairline/grow_v2` | 同接口11 + 重绘带参数 | final 基底 + Flux-2 保色重绘（整帧/局部两版）；精简版 `grow_v2_final[_v2]` 仅需图片+hairline_id |
+| 99 人脸特殊点 | `/api/v1/face/special-points` | 用户照片 | 60 个固定编号关键点 + 5 个发际线特殊点像素坐标 JSON |
+
+> 另有 worker 本机工具路由（不在对外契约内）：`/api/swapHair/v1`、`/hairColor/v2`（CORS 代理 change_hair）、`/api/v1/redraw`（直接 ComfyUI 重绘）、`/api/v1/debug/*`。

 ---

@@ -534,7 +718,7 @@
 - 默认单人；检测到 2~3 人报错提示客户端；单文件 **≤ 1 MB**；格式仅 **JPG / PNG**。
 - 所有坐标基准：**原图像素**。
 - 接口 2：提供「美颜」开关 `beauty_enabled`。
- 接口 3：需同时上传原图，需返回发际线类型。
+- 接口 3：仅传**划线图**（`marked_image_*` 三选一），需返回发际线类型（`custom`）。
 - 接口 4：`data` 返回**一个 JSON 字符串**，字段不固定，可随时调整。
 - 接口 5：发际线 PNG 数量 **N 不固定**，需按合适度**排序**。
 - 英文字段命名由本文档约定（见各接口表格）。