feat(接口2/7): 接口2加hair_style参数选单张发型；新增接口7用add_hair2工作流
接口2 变更： - 新增必填 hair_style(int) 参数，按序号只生成一张(不再全量) - female:1-5 male:1-4，越界返回1007 接口7 新增： - POST /api/v1/hair/grow-v2，功能与接口2一致 - 使用 add_hair2.json 工作流(Flux-2 Klein 9b) - SaveImage输出节点自动检测(75) comfyui.py 重构： - run() 支持 workflow_path 参数，多工作流按路径缓存 - SaveImage 输出节点自动检测，不再硬编码 - 输入/种子/提示词节点ID两个工作流相同(26/6/60) 文档： - 接口文档、实现说明、网关待改动 三份同步更新 - 网关只需加一行路由，base64→URL改写无需改动 Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
+13
-4
@@ -13,7 +13,7 @@
|
||||
```
|
||||
客户端 ──HTTPS──> 外网网关(gateway/) ──HTTP(X-Internal-Token)──> worker(GPU 机, app.py)
|
||||
│ 薄代理 + 落盘改URL │ 跑算法(本地模型/ComfyUI)
|
||||
└ 接口4 本机直接调豆包(不转发) └ 接口1/2/3/5
|
||||
└ 接口4 本机直接调豆包(不转发) └ 接口1/2/3/5/7
|
||||
```
|
||||
|
||||
- **worker**（`app.py` + `face_analysis/` + `hairline/`）：跑真正的算法，**纯本地、无外网依赖**。
|
||||
@@ -32,6 +32,7 @@
|
||||
| 2 | `results[].image_base64` / `results[].grown_image_base64`(可空) | `results[].image_url` / `results[].grown_image_url` |
|
||||
| 3 | `hair_growth_image_base64`(可空) | `hair_growth_image_url` |
|
||||
| 5 | `hairline_images[].image_base64` | `hairline_images[].image_url` |
|
||||
| 7 | `results[].image_base64` / `results[].grown_image_base64`(可空) | `results[].image_url` / `results[].grown_image_url` |
|
||||
| 4 | （网关本机产出，无图片字段，`features` 为 JSON 字符串） | — |
|
||||
|
||||
> 实现建议：递归遍历 data，凡 key 以 `_base64` 结尾就落盘改 `_url`，自动覆盖嵌套/新增字段。
|
||||
@@ -40,7 +41,7 @@
|
||||
|
||||
### 错误码
|
||||
|
||||
`1001` 无法识别人像 ｜ `1002` 分辨率过低 ｜ `1003` 非正面 ｜ `1004` gender 必填/非法（接口2/5）｜
|
||||
`1001` 无法识别人像 ｜ `1002` 分辨率过低 ｜ `1003` 非正面 ｜ `1004` gender 必填/非法（接口2/5/7）｜
|
||||
`1006` >1MB ｜ `1007` 图片参数错误（0或多个）/未预期异常 ｜ `1008` 格式不支持。
|
||||
|
||||
---
|
||||
@@ -55,11 +56,19 @@
|
||||
- 门槛可配：`MIN_SHORT_SIDE`/`MIN_LONG_SIDE`(默认600/800)、姿态阈值 `FRONTAL_*_THR`(默认30°)。
|
||||
|
||||
### 接口2 C端生发 `/api/v1/hair/grow`（worker）—— 预览 + 生发图
|
||||
- **做什么**：正面照 + `gender`(必填) → 该性别全部发际线(female5/male4) 各一组：**预览图**(发际线叠在照片上) + **生发后图**(植发3个月效果)。
|
||||
- **做什么**：正面照 + `gender`(必填) + `hair_style`(必填，int) → 指定发际线类型 **1 组**：**预览图**(发际线叠在照片上) + **生发后图**(植发3个月效果)。
|
||||
- **怎么实现**（`hairline/`）：移植 head3d——MediaPipe(Tasks) + SegFormer 分割 + 17 锚点射线检测 → 502 点 mesh，
|
||||
按 `face_ext.obj` 的 UV 把发际线贴图渲染到额头(预览)。生发：黑贴图渲染遮罩 → 调本机 **ComfyUI 8182** 的
|
||||
`add_hair.json`(Flux-2) 出图。**关键坑**：obj 是重排序，需 `INDEX_MAP_468` 把 MP 序→OBJ 序。
|
||||
同步、一次 N 张(~18s)。返回 `results[].image_base64` + `grown_image_base64`。
|
||||
单张请求(~5s)。返回 `results[].image_base64` + `grown_image_base64`。
|
||||
- `hair_style` 映射：female 1=ellipse 2=flower 3=heart 4=straight 5=wave；male 1=ellipse 2=inverse_arc 3=m 4=straight。
|
||||
|
||||
### 接口7 C端生发 v2 `/api/v1/hair/grow-v2`（worker）—— 接口2同款，add_hair2 工作流
|
||||
- **做什么**：与接口 2 完全一致（正面照 + `gender` + `hair_style` → 1 组预览+生发图）。
|
||||
- **与接口 2 的唯一区别**：ComfyUI 工作流使用 `add_hair2.json`（Flux-2 Klein 9b），输入/遮罩节点同为 26，
|
||||
SaveImage 输出节点为 75（自动检测）。其他参数、响应结构、错误码**完全相同**。
|
||||
- **网关改动**：在 `gateway/app.py` 新增路由 `POST /api/v1/hair/grow-v2`，转发到 worker 同路径即可（盲转发，
|
||||
base64→URL 改写逻辑无需改动，数组内图片字段已覆盖）。详见 [`网关待改动.md`](网关待改动.md)。
|
||||
|
||||
### 接口3 B端生发 `/api/v1/hair/grow-b`（worker）—— 马克笔发际线
|
||||
- **做什么**：医生用马克笔在额头画好发际线，**只传这一张划线图** → 检测线 → 生发图。输出 `hair_growth_image_url` + `hairline_type="custom"`。
|
||||
|
||||
+63
-7
@@ -19,6 +19,7 @@
|
||||
| 3 B 端生发 | POST | `/api/v1/hair/grow-b` |
|
||||
| 4 用户特征 | POST | `/api/v1/face/features` |
|
||||
| 5 发际线 PNG 生成 | POST | `/api/v1/hairline/generate` |
|
||||
| 7 C 端生发 v2 | POST | `/api/v1/hair/grow-v2` |
|
||||
|
||||
---
|
||||
|
||||
@@ -177,9 +178,9 @@
|
||||
|
||||
## 接口 2：C 端生发接口
|
||||
|
||||
**说明**：输入用户正面照 + 性别，按性别对应的发际线类型，逐张把建议发际线渲染到照片上，输出多张方案。
|
||||
**说明**：输入用户正面照 + 性别 + 发型序号，按指定发际线类型渲染一张预览图 + 生发图。
|
||||
|
||||
> **每个方案返回两张图**：`image_url`=「原照片 + 发际线曲线叠加的**预览图**」；`grown_image_url`=
|
||||
> **每个请求返回两张图**：`image_url`=「原照片 + 发际线曲线叠加的**预览图**」；`grown_image_url`=
|
||||
> 经 ComfyUI/Flux 的「植发 3 个月**生发后图片**」。两者均已实现，实现简述见 [`实现说明.md`](实现说明.md)。
|
||||
|
||||
**请求**：`POST /api/v1/hair/grow`
|
||||
@@ -191,12 +192,13 @@
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| gender | string | **是** | 性别：`male` / `female`。决定使用的发际线贴图集合 |
|
||||
| hair_style | int | **是** | 发型序号，1-indexed。female：1=ellipse, 2=flower, 3=heart, 4=straight, 5=wave；male：1=ellipse, 2=inverse_arc, 3=m, 4=straight。越界返回 `1007` |
|
||||
| beauty_enabled | bool | 否 | 生发图是否带美颜效果，默认 false（当前阶段不生效） |
|
||||
| use_mask | bool | 否 | 是否启用 inpaint 遮罩，默认 `true`。`false` 时用干净原图生成（空遮罩、不烧模板黑线），供测试对比；此时 N 张结果共用同一张生发图 |
|
||||
| use_mask | bool | 否 | 是否启用 inpaint 遮罩，默认 `true`。`false` 时用干净原图生成（空遮罩、不烧模板黑线），供测试对比 |
|
||||
|
||||
### 输出（data）
|
||||
|
||||
`results`：发际线方案数组，**数量 = 该性别的发际线类型数**（`female` 5 个 / `male` 4 个）。每个元素：
|
||||
`results`：发际线方案数组，**含 1 个元素**（指定发型）。每个元素：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
@@ -205,8 +207,8 @@
|
||||
| hairline_type | string | 发际线类型 key：`ellipse`/`flower`/`heart`/`straight`/`wave`（female），`ellipse`/`m`/`straight`/`inverse_arc`（male） |
|
||||
| order | int | 排序序号（当前阶段固定 `1..N`，按贴图顺序，暂不计算合适度） |
|
||||
|
||||
> ⚠️ 生发图由本机 ComfyUI（Flux-2，端口 8182）生成，**一次请求生成全部 N 张、同步返回**，
|
||||
> 单请求耗时可达数分钟，调用方超时需放大。worker 侧返回 `image_base64` / `grown_image_base64`，
|
||||
> ⚠️ 生发图由本机 ComfyUI（Flux-2，端口 8182）生成，**一次请求生成指定发型的 1 张、同步返回**。
|
||||
> worker 侧返回 `image_base64` / `grown_image_base64`，
|
||||
> 网关落盘后改写为上表的 `image_url` / `grown_image_url`。
|
||||
|
||||
### 响应示例
|
||||
@@ -361,15 +363,69 @@
|
||||
|
||||
---
|
||||
|
||||
## 接口 7：C 端生发 v2 接口
|
||||
|
||||
**说明**：功能与[接口 2](#接口-2c-端生发接口)完全一致，仅 ComfyUI 工作流不同——使用 `add_hair2.json` 替代 `add_hair.json`。
|
||||
|
||||
**请求**：`POST /api/v1/hair/grow-v2`
|
||||
|
||||
### 输入
|
||||
|
||||
与接口 2 完全相同。图片参数见「通用约定 → 图片传参字段」。专属参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| gender | string | **是** | 性别：`male` / `female`。决定使用的发际线贴图集合 |
|
||||
| hair_style | int | **是** | 发型序号，1-indexed。female：1=ellipse, 2=flower, 3=heart, 4=straight, 5=wave；male：1=ellipse, 2=inverse_arc, 3=m, 4=straight。越界返回 `1007` |
|
||||
| beauty_enabled | bool | 否 | 生发图是否带美颜效果，默认 false（当前阶段不生效） |
|
||||
| use_mask | bool | 否 | 是否启用 inpaint 遮罩，默认 `true`。`false` 时用干净原图生成（空遮罩、不烧模板黑线） |
|
||||
|
||||
### 输出（data）
|
||||
|
||||
与接口 2 完全相同。`results`：发际线方案数组，**含 1 个元素**。每个元素：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| image_url | string | 方案**预览图** URL（发际线曲线叠加图） |
|
||||
| grown_image_url | string | **生发后图片** URL（ComfyUI/Flux「植发 3 个月」效果图） |
|
||||
| hairline_type | string | 发际线类型 key |
|
||||
| order | int | 排序序号 |
|
||||
|
||||
> ⚠️ 与接口 2 的区别：本接口使用 `add_hair2.json` 工作流（Flux-2 Klein 9b），输入/遮罩节点同为 26，
|
||||
> SaveImage 输出节点为 75。
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"request_id": "mock-request-id",
|
||||
"data": {
|
||||
"results": [
|
||||
{
|
||||
"image_url": "https://hair.xiangsilian.com/static/sample.jpg",
|
||||
"grown_image_url": "https://hair.xiangsilian.com/static/sample.jpg",
|
||||
"hairline_type": "ellipse",
|
||||
"order": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 汇总：输入输出一览
|
||||
|
||||
| 接口 | 输入 | 主要输出 |
|
||||
|------|------|----------|
|
||||
| 1 四庭七眼测量 | 用户照片 | 标注 PNG（无人物）+ 四庭/七眼厘米数值与坐标 |
|
||||
| 2 C 端生发 | 用户照片 | 生发后图片 + 多张发际线（带类型与排序） |
|
||||
| 2 C 端生发 | 用户照片 | 生发后图片 + 指定发际线预览（单张） |
|
||||
| 3 B 端生发 | 划线图片 | 最合适发际线图片 + 生发后图片 |
|
||||
| 4 用户特征 | 用户照片 | 6 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格） |
|
||||
| 5 发际线 PNG | 用户照片 | N 张发际线 PNG + 最合适发际线面部中间点坐标 |
|
||||
| 7 C 端生发 v2 | 用户照片 + gender + hair_style | 同接口2，使用 add_hair2.json 工作流 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -44,6 +44,73 @@ filename = f"{uuid.uuid4().hex}.{ext}"
|
||||
|
||||
---
|
||||
|
||||
## 5. 🔲【新增】接口7 C端生发 v2（`/api/v1/hair/grow-v2`）
|
||||
|
||||
**背景**：worker 侧已新增接口 7，功能与接口 2 完全一致，区别仅在于 ComfyUI 工作流使用 `add_hair2.json`（而非 `add_hair.json`）。
|
||||
|
||||
**网关需新增一个路由**，代理转发到 worker 的同路径：
|
||||
|
||||
```python
|
||||
# gateway/app.py
|
||||
|
||||
@app.post("/api/v1/hair/grow-v2", tags=["生发"])
|
||||
async def hair_grow_v2(request: Request):
|
||||
"""接口7：C端生发 v2（add_hair2 工作流）"""
|
||||
return await _proxy(request, "/api/v1/hair/grow-v2")
|
||||
```
|
||||
|
||||
**无需额外改动**：
|
||||
- 请求：multipart/form-data，参数与接口 2 完全相同（`image_file/url/base64` 三选一 + `gender` + `hair_style` + `beauty_enabled` + `use_mask` + `prompt`），网关盲转发即可
|
||||
- 响应：结构与接口 2 完全一致，`results[].image_base64` / `results[].grown_image_base64` 经现有 `rewrite_base64_to_url` 自动改写为 URL
|
||||
- base64→URL：数组内图片字段递归改写已覆盖，无需修改
|
||||
|
||||
### 入参（与接口 2 一致）
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| image_file / image_url / image_base64 | — | **三选一** | 用户正面照 |
|
||||
| gender | string | **是** | `male` / `female` |
|
||||
| hair_style | int | **是** | 发型序号。female: 1–5，male: 1–4 |
|
||||
| beauty_enabled | bool | 否 | 美颜开关（本期不生效） |
|
||||
| use_mask | bool | 否 | 默认 `true`，`false` 跳过遮罩 |
|
||||
| prompt | string | 否 | ComfyUI 提示词 |
|
||||
|
||||
### 出参（与接口 2 一致）
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"request_id": "gw-xxxxxxxx",
|
||||
"data": {
|
||||
"results": [
|
||||
{
|
||||
"image_url": "https://hair.xiangsilian.com/static/annotations/xxx.jpg",
|
||||
"grown_image_url": "https://hair.xiangsilian.com/static/annotations/xxx.jpg",
|
||||
"hairline_type": "ellipse",
|
||||
"order": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### worker 侧信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| worker 路径 | `/api/v1/hair/grow-v2` |
|
||||
| 工作流文件 | `add_hair2.json` |
|
||||
| 输入/遮罩节点 | 26（LoadImage） |
|
||||
| 输出节点 | 75（SaveImage，自动检测） |
|
||||
| 提示词节点 | 60（JjkText） |
|
||||
|
||||
### 🔲【可选·仅影响 /docs】OpenAPI 表单声明
|
||||
|
||||
若想让网关 `/docs` 展示准确，在 `gateway/app.py` 新增 `_GROW_V2_FORMS`（或复用 `_GROW_FORMS` 并补充 `gender`/`hair_style` 字段），然后将路由函数签名改为显式声明 Form 参数（参考接口 4 的写法）。不改也不影响实际转发。
|
||||
|
||||
---
|
||||
|
||||
## 已经做好、无需再动的
|
||||
|
||||
- **接口4 在网关本机实现**（调豆包，不转发 worker）——已完成；config 里配 `ark`。
|
||||
|
||||
Reference in New Issue
Block a user