From f509fe99b4ea678c1f176634b89bf4d034cb5b1a Mon Sep 17 00:00:00 2001 From: xsl Date: Fri, 24 Jul 2026 00:42:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20integration.html?= =?UTF-8?q?=20/=20=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3.md=20/=20test=5Fint?= =?UTF-8?q?erface5.html?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 接口5: 补 generate_grow_image 参数说明(接口文档/integration/test_interface5 加控件) - 接口1/5/6: 补 left_position/right_position 字段(MediaPipe 21/251号点) - 接口4: features 字段纠正为固定6个英文字段(原误写~42项含中文, 与代码不符) - 接口7: 完全移除(代码已 deprecated=True 固定返回错误, 文档却当正常接口详述) - 错误码: 删错误的'1004已废弃'(1004仍用于接口2/5 gender校验), 补 1004 正确描述 + 1009(X-Internal-Token鉴权) - test_interface5.html: 加 generate_grow_image 复选框 --- docs/接口文档.md | 66 +++++-------------------------------- static/integration.html | 56 +++++++++---------------------- static/test_interface5.html | 8 ++++- 3 files changed, 32 insertions(+), 98 deletions(-) diff --git a/docs/接口文档.md b/docs/接口文档.md index ac45ce3..f8e770c 100644 --- a/docs/接口文档.md +++ b/docs/接口文档.md @@ -20,7 +20,6 @@ | 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` | --- @@ -87,6 +86,7 @@ | 1006 | 文件超出大小限制 | 单文件超过 1 MB | | 1007 | 图片参数错误 | file / url / base64 未传，或同时传了多个（三者严格互斥） | | 1008 | 图片格式不支持 | 非 JPG / PNG | +| 1009 | 未授权 | 缺少或错误的 `X-Internal-Token`（`/api/*` 路径鉴权） | --- @@ -109,6 +109,8 @@ | four_courts | object | 四庭数据，见下表 | | seven_eyes | object | 七眼数据，见下表 | | landmarks | object | 关键分界点坐标（头顶 / 发际线 / 眉心 / 鼻翼下缘 / 下巴尖），原图像素坐标 | +| left_position | object | MediaPipe 21 号关键点坐标（左脸定位点），原图像素：`{ "x": int, "y": int }` | +| right_position | object | MediaPipe 251 号关键点坐标（右脸定位点，与 21 号镜像），原图像素：`{ "x": int, "y": int }` | `four_courts`（四庭，自上而下）： @@ -211,6 +213,8 @@ | four_courts | object | 三庭数据（上/中/下庭，各含 cm 与 ratio；**无顶庭**） | | seven_eyes | object | 七眼数据（眼宽/脸宽/两眼间距 cm + 占比 ratios + **eye2~eye6** 共 5 段宽度） | | landmarks | object | 四个关键点像素坐标（发际线/眉心/鼻翼下缘/下巴尖） | +| left_position | object | MediaPipe 21 号关键点坐标（左脸定位点），原图像素：`{ "x": int, "y": int }` | +| right_position | object | MediaPipe 251 号关键点坐标（右脸定位点，与 21 号镜像），原图像素：`{ "x": int, "y": int }` | > 接口6 是**三庭五眼**：`four_courts`/`landmarks` 不含顶庭与头顶点（无 `top_court_cm`/`hair_top`）；`seven_eyes` 只含 **eye2~eye6**（左脸颊/左眼/两眼间距/右眼/右脸颊，5 段），**无 eye1/eye7**（耳外段需头发轮廓端线，仅接口1 有）。 @@ -405,6 +409,7 @@ | hair_style | string | **是** | 发型序号，**逗号分隔多选**（如 `1,2,3`），决定返回哪些发际线类型。female：1=ellipse, 2=flower, 3=heart, 4=straight, 5=wave；male：1=ellipse, 2=inverse_arc, 3=m, 4=straight。缺失/越界/非法返回 `1007` | | use_mask | bool | 否 | 生发是否启用 inpaint 遮罩，默认 `true`。`false` 时用干净原图生成（空遮罩、不烧模板黑线），供测试对比 | | prompt | string | 否 | ComfyUI 提示词，默认「补充遮罩区域的头发，加一点美颜」，会替换工作流节点 60 的文本 | +| generate_grow_image | bool | 否 | 是否生成生发效果图（ComfyUI 生发，全流程最耗时），默认 `true`。传 `false` 时跳过生发，各发型 `grown_image_*` 恒为 `null`，仅返回三档发际线叠图与中心点，可大幅降低耗时 | > ⚠️ 三档叠图分别用 `hairline_texture` / `hairline_texture_high` / `hairline_texture_low` 三套同名贴图；**生发黑模板固定取自 `hairline_texture_black/`（middle 档）**，即生发目标固定压到 middle 档，每个发型仅 1 张生发图。 @@ -426,7 +431,7 @@ | image_middle_url | string | middle 档发际线曲线**透明 PNG** URL（仅曲线，透明底，**不含人物**，需叠加原图显示） | | image_high_url | string | high 档发际线曲线**透明 PNG** URL（同上，high 档曲线） | | image_low_url | string | low 档发际线曲线**透明 PNG** URL（同上，low 档曲线） | -| grown_image_url | string \| null | **生发后图片** URL（ComfyUI「植发」效果图，完整人像照片，生发失败时为 `null`） | +| grown_image_url | string \| null | **生发后图片** URL（ComfyUI「植发」效果图，完整人像照片，生发失败或 `generate_grow_image=false` 时为 `null`） | | order | int | 发型序号（= 传入的 hair_style 值） | > worker 侧返回 `image_middle_base64` / `image_high_base64` / `image_low_base64` / `grown_image_base64`，网关落盘后改写为上表对应的 `*_url`。 @@ -443,6 +448,8 @@ | landmarks | object | 5 个纵向关键点像素坐标（hair_top/hairline/brow_center/nose_bottom/chin_tip），结构同接口1 | | hairline_source | string | 发际线来源：`segmentation`（真实分割）/ `estimated`（比例估算） | | head_pose | object | 头部姿态角度（yaw/pitch/roll，单位：度） | +| left_position | object | MediaPipe 21 号关键点坐标（左脸定位点），原图像素：`{ "x": int, "y": int }` | +| right_position | object | MediaPipe 251 号关键点坐标（右脸定位点，与 21 号镜像），原图像素：`{ "x": int, "y": int }` | > `eye1`~`eye7` 为从左到右共 7 段宽度，eye1=左耳外段、eye7=右耳外段，某侧耳朵不可见时对应段为 `null`。详见接口1说明。 @@ -508,60 +515,6 @@ --- -## 接口 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 | string | **是** | 发型序号，**逗号分隔多选**（如 `1,2,3`）。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` 时用干净原图生成（空遮罩、不烧模板黑线） | -| prompt | string | 否 | ComfyUI 提示词，默认「补充遮罩区域的头发，加一点美颜」，会替换工作流节点 60 的文本 | - -### 输出（data） - -与接口 2 完全相同。`results`：发际线方案数组，**数量 = 所选发型数**。每个元素： - -| 字段 | 类型 | 说明 | -|------|------|------| -| image_url | string | 发际线曲线**透明 PNG** 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 - } - ] - } -} -``` - ---- - ## 汇总：输入输出一览 | 接口 | 输入 | 主要输出 | @@ -572,7 +525,6 @@ | 3 B 端生发 | 划线图片 | 最合适发际线图片 + 生发后图片 | | 4 用户特征 | 用户照片 | 6 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格） | | 5 发际线 PNG | 用户照片 + gender + hair_style（多选） | 每个选中发型 middle/high/low 三档发际线叠图 + 生发图 + 最合适发际线面部中间点坐标 | -| 7 C 端生发 v2 | 用户照片 + gender + hair_style | 同接口2，使用 add_hair2.json 工作流 | --- diff --git a/static/integration.html b/static/integration.html index 1fedc39..52c346d 100644 --- a/static/integration.html +++ b/static/integration.html @@ -57,7 +57,6 @@ 接口4 接口5 接口6 - 接口7 错误码 在线测试 @@ -109,6 +108,8 @@ landmarksobject5 个关键点像素坐标：hair_top/hairline/brow_center/nose_bottom/chin_tip hairline_sourcestring发际线来源："segmentation"（真实分割，可信度高）/ "estimated"（比例估算，可信度低） head_poseobject头部姿态角度：{ yaw, pitch, roll }（度），接近 0 表示正面照 + left_positionobjectMediaPipe 21 号关键点坐标（左脸定位点），原图像素：{ x: number, y: number } + right_positionobjectMediaPipe 251 号关键点坐标（右脸定位点，与 21 号镜像），原图像素：{ x: number, y: number }

💡 前端把标注图叠加到原图上即可呈现测量效果（标注图白色线条 #FFFFFF，透明底）。

@@ -189,17 +190,17 @@ const { code, data } = await res.json();

4. 用户特征分析  POST  /api/v1/face/features

-

上传照片 → 火山方舟豆包视觉模型分析 → 返回几十项面部特征（脸型/眉形/肤色/四季色彩…）。

+

上传照片 → 火山方舟豆包视觉模型分析 → 返回固定 6 项面部特征（脸型/眉形/面部年龄/动静类型/性别/基因风格）。

入参：image_file / image_url / image_base64 三选一。无其他参数。

data 字段

- +
字段类型说明
featuresstringJSON 字符串（不是对象！客户端需 JSON.parse()）
featuresstringJSON 字符串（不是对象！客户端需 JSON.parse()）。解析后得到固定 6 个英文字段
-

features 英文优先字段（其余中文字段同时返回，共~42个）：

+

features 字段（固定返回 6 个）：

@@ -214,7 +215,7 @@ const { code, data } = await res.json(); const { code, data } = await res.json(); const features = JSON.parse(data.features); // ← 注意：data.features 是字符串！ console.log(features.face_shape); // "鹅蛋脸" -console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保留） +console.log(features.gene_style); // "自然型" @@ -230,12 +231,13 @@ console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保 +
字段说明字段说明
face_shape脸型eyebrow_shape眉形
image_file / image_url / image_base64—三选一用户正面照
genderstring✅ 必填"male" / "female"
hair_stylestring✅ 必填发型序号，逗号分隔多选（如 1,2,3）。缺失/越界返回 1007
generate_grow_imagebool否是否生成生发效果图（ComfyUI 生发，全流程最耗时），默认 true。传 false 时跳过生发，各发型 grown_image_url 恒为 null，仅返回三档发际线叠图与中心点，大幅降低耗时

data 字段

- + @@ -251,6 +253,8 @@ console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保 + +
字段类型说明
hairline_images[]object[]选中发型列表，每项含 hairline_type、image_middle_url/image_high_url/image_low_url 三档透明 PNG 叠图（仅曲线，需叠加原图）、grown_image_url 生发图（完整人像，失败为 null）、order
hairline_images[]object[]选中发型列表，每项含 hairline_type、image_middle_url/image_high_url/image_low_url 三档透明 PNG 叠图（仅曲线，需叠加原图）、grown_image_url 生发图（完整人像，失败或 generate_grow_image=false 时为 null）、order
best_hairline_center_pointobject \| null首个选中发型 middle 档发际线中心点像素坐标 { x: number, y: number }
high_hairline_center_pointobject \| null同上，high 档发际线中点（发际线偏高，y 更小）
low_hairline_center_pointobject \| null同上，low 档发际线中点（发际线偏低，y 更大）
landmarksobject5 个关键点像素坐标：hair_top/hairline/brow_center/nose_bottom/chin_tip
hairline_sourcestring发际线来源："segmentation"（真实分割）/ "estimated"（比例估算）
head_poseobject头部姿态角度：{ yaw, pitch, roll }（度）
left_positionobjectMediaPipe 21 号关键点坐标（左脸定位点），原图像素：{ x: number, y: number }
right_positionobjectMediaPipe 251 号关键点坐标（右脸定位点，与 21 号镜像），原图像素：{ x: number, y: number }

💡 前端无需额外请求接口1 即可拿到四庭七眼测量数值；face_measure 为 null 时（角度过大/无人脸等）仅隐藏测量区块，发际线结果照常展示。

@@ -282,41 +286,12 @@ console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保 four_courtsobject三庭：upper/middle/lower，各含 _cm 和 ratios（无 top_court） seven_eyesobject七眼：eye_width_cm/face_width_cm/inter_eye_distance_cm + ratios + eye2~eye6（左脸颊/左眼/两眼间距/右眼/右脸颊，5 段宽度 cm；无 eye1/eye7） landmarksobject4 个关键点：hairline/brow_center/nose_bottom/chin_tip（无 hair_top） + left_positionobjectMediaPipe 21 号关键点坐标（左脸定位点），原图像素：{ x: number, y: number } + right_positionobjectMediaPipe 251 号关键点坐标（右脸定位点，与 21 号镜像），原图像素：{ x: number, y: number }
- -
-

7. C端生发 v2  POST  /api/v1/hair/grow-v2  v2

-
-

功能与接口2完全一致，仅 ComfyUI 工作流不同——使用 add_hair2.json 替代 add_hair.json（Flux-2 Klein 9b）。

- -

入参

- - - - - -
参数类型必填说明
image_file / image_url / image_base64—三选一用户正面照
genderstring✅ 必填"male" / "female"
hair_styleint✅ 必填发型序号。female: 1~5，male: 1~4
- -

data.results[] 元素（同接口2）

- - - - - - -
字段类型说明
image_urlstring发际线曲线透明 PNG（仅曲线，需叠加原图显示，同接口2）
grown_image_urlstring生发后效果图（完整人像）⚠ 可空
hairline_typestring发际线类型 key
orderint排序
- -

- Female 5 种：ellipse/flower/heart/straight/wave  |  - Male 4 种：ellipse/m/straight/inverse_arc
- ⚠ 工作流: add_hair2.json（Flux-2 Klein 9b），输入节点 26，输出节点 75。 -

-
-
-

⚠ 错误码

@@ -326,12 +301,14 @@ console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保 1001无法识别人像未检测到人脸 1003角度问题，非正面照非正面 / 角度过大 + 1004gender 必填且只能为 male / female接口2/5 的 gender 缺失或非法 1005检测到多张人脸仅支持单人 1007图片参数错误 / 后端不可用参数传错 / 服务繁忙请稍后重试 1008图片格式不支持非 JPG/PNG / base64 解码失败 + 1009未授权缺少或错误的 X-Internal-Token（/api/* 路径鉴权） -

1004 已废弃（接口2 不再自动判性别，改由客户端传 gender 参数）。

+

注：1004 仍在使用（接口2/5 的 gender 校验）；接口7（grow-v2）已弃用，请改用接口2。

@@ -344,10 +321,9 @@ console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保 1. 四庭七眼/static/test_interface1.html上传照片 → 原图+标注叠加，底图/标注开关，指标卡片 2. C端生发/static/test_interface2.html上传+性别 → 方案一覧（原图/叠加/生发），双图对比 3. B端生发/static/test_interface3.html划线图上传 → 生发效果图 - 4. 用户特征/static/test_interface4.html上传照片 → 42项面部特征表格 + 原始JSON + 4. 用户特征/static/test_interface4.html上传照片 → 6项面部特征 + 原始JSON 5. 发际线PNG/static/test_interface5.html上传+性别 → 发际线方案+中心点坐标 6. 四庭七眼 v2/static/test_interface6.html同接口1，去顶庭 · 竖线发际线→下巴 · 无头部端线 - 7. C端生发 v2/static/test_interface7.html同接口2，使用 add_hair2.json 工作流（Flux-2 Klein 9b）

完整 API 文档：/docs（Swagger UI） diff --git a/static/test_interface5.html b/static/test_interface5.html index a104330..bf4d2d1 100644 --- a/static/test_interface5.html +++ b/static/test_interface5.html @@ -113,6 +113,12 @@ +

+ + +
@@ -206,7 +212,7 @@ async function submitTest() { $('submitBtn').disabled = true; $('submitBtn').textContent = '⏳ ...'; setStatus('请求中...', 'info'); $('resultsArea').classList.add('hidden'); - const fd = new FormData(); fd.append('image_file', f); fd.append('gender', $('gender').value); fd.append('hair_style', checked.join(',')); + const fd = new FormData(); fd.append('image_file', f); fd.append('gender', $('gender').value); fd.append('hair_style', checked.join(',')); fd.append('generate_grow_image', $('genGrowImg').checked ? 'true' : 'false'); const _reqStart = performance.now(); try { const r = await fetch(API_BASE + '/api/v1/hairline/generate', { method:'POST', headers: { 'X-Internal-Token': 'dev-shared-secret-2026' }, body:fd });