# 旷视五个接口 — 接口文档（输入 / 输出定义）

> 本文档依据《旷视具体需求.docx》整理，描述各接口的**输入**与**输出**。
> 文中标记为 **【待确认】** 的内容为需求文档中尚未明确、需与对方对齐的点。

> **当前为第一版 Mock 服务**：所有接口已上线，但**不做真实算法计算**，统一返回下文「响应示例」中的默认值；所有图片字段均返回示例图 `https://hair.xiangsilian.com/static/sample.jpg`。真实逻辑后续接入。

---

## 服务地址与接口路径

- **Base URL**：`https://hair.xiangsilian.com`
- **在线接口文档（Swagger）**：`https://hair.xiangsilian.com/docs`

| 接口 | 方法 | 路径 |
|------|------|------|
| 1 四庭七眼测量 | POST | `/api/v1/face/measure` |
| 6 四庭七眼测量 v2 | POST | `/api/v1/face/measure-v2` |
| 2 C 端生发 | POST | `/api/v1/hair/grow` |
| 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` |

---

## 通用约定

以下约定适用于全部 5 个接口（最终以联调为准）。

### 请求

| 项目 | 约定 |
|------|------|
| 协议 | HTTPS |
| 请求方式 | `POST` |
| 图片传参方式 | 三选一，三种都支持：① `multipart/form-data` 上传文件、② 图片 URL、③ base64 字符串 |
| 字符编码 | UTF-8 |
| 坐标基准 | 所有返回的坐标均以**原图像素**为基准（原点为图片左上角，x 向右、y 向下） |

图片传参字段（三者**严格互斥**，必须且只能传其一；传了 0 个或 ≥2 个均报错）：

| 参数 | 类型 | 说明 |
|------|------|------|
| image_file | file | 上传文件（`multipart/form-data`） |
| image_url | string | 图片 URL |
| image_base64 | string | 图片 base64 字符串，**需带前缀**，如 `data:image/png;base64,xxxx` |

### 图片输入要求（接口 1/2/3/4/5 通用）

| 项目 | 要求 |
|------|------|
| 图片类型 | 用户正面照（人像） |
| 人脸数量 | 默认仅支持**单人**；若检测到 2 或 3 张人脸（即多人），报错并提示客户端 |
| 单文件大小 | ≤ 1 MB |
| 最低分辨率 | 720 × 1024 |
| 最大分辨率 | 2160 × 3840 |
| 格式 | 目前仅支持 JPG / PNG |

### 统一响应结构

```json
{
  "code": 0,
  "message": "success",
  "request_id": "唯一请求标识",
  "data": { }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 0 表示成功，非 0 表示失败 |
| message | string | 结果描述 / 错误原因 |
| request_id | string | 请求追踪 ID |
| data | object | 业务数据，结构见各接口 |

### 通用错误码（识别失败时返回，见需求文档）

| code | message | 说明 |
|------|---------|------|
| 1001 | 无法识别人像 | 图片中未检测到人脸 |
| 1002 | 人像分辨率过低 | 低于最低分辨率要求 |
| 1003 | 角度问题，非正面照 | 非正面 / 角度过大 |
| 1004 | gender 必填/非法 | 接口2/5 的 `gender` 缺失或非 `male`/`female` |
| 1005 | 检测到多张人脸 | 默认仅支持单人，检测到 2 人或以上时返回 |
| 1006 | 文件超出大小限制 | 单文件超过 1 MB |
| 1007 | 图片参数错误 | file / url / base64 未传，或同时传了多个（三者严格互斥） |
| 1008 | 图片格式不支持 | 非 JPG / PNG |

---

## 接口 1：四庭七眼测量标注接口

**说明**：输入用户照片，输出一张标注好四庭七眼数据的 PNG 图片（**不包含人物本体，仅标注图层**），同时返回四庭、七眼的比例与厘米数值。

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

### 输入

图片参数见「通用约定 → 图片传参字段」（`image_file` / `image_url` / `image_base64` 三选一）。本接口无其他专属参数。

### 输出（data）

| 字段 | 类型 | 说明 |
|------|------|------|
| annotated_image_url | string | 标注好数据的 PNG 图片（仅标注图层，不含人物） |
| face_total_height_cm | number | 全脸总高度（cm） |
| four_courts | object | 四庭数据，见下表 |
| seven_eyes | object | 七眼数据，见下表 |
| landmarks | object | 关键分界点坐标（头顶 / 发际线 / 眉心 / 鼻翼下缘 / 下巴尖），原图像素坐标 |

`four_courts`（四庭，自上而下）：

| 字段 | 类型 | 说明 |
|------|------|------|
| top_court_cm | number | 顶庭长度（cm），示例：约占全脸高度 22% |
| upper_court_cm | number | 上庭长度（cm），约占 25% |
| middle_court_cm | number | 中庭长度（cm），约占 28% |
| lower_court_cm | number | 下庭长度（cm），约占 25% |
| ratios | object | 各庭占全脸高度的百分比 |

`seven_eyes`（七眼，横向）：

| 字段 | 类型 | 说明 |
|------|------|------|
| eye_width_cm | number | 单眼宽度（cm） |
| face_width_cm | number | 脸宽（cm） |
| inter_eye_distance_cm | number | 两眼间距（cm） |
| ratios | object | 七眼各段占脸宽的比例 |
| eye1 | number \| null | 从左到右第 1 段宽度（cm）：人头最左 → 左脸颊（左耳外侧段）。该侧耳朵不可见时为 null |
| eye2 | number | 从左到右第 2 段宽度（cm）：左脸颊 → 左眼外角 |
| eye3 | number | 从左到右第 3 段宽度（cm）：左眼外角 → 左眼内角（左眼宽度） |
| eye4 | number | 从左到右第 4 段宽度（cm）：左眼内角 → 右眼内角（两眼间距） |
| eye5 | number | 从左到右第 5 段宽度（cm）：右眼内角 → 右眼外角（右眼宽度） |
| eye6 | number | 从左到右第 6 段宽度（cm）：右眼外角 → 右脸颊 |
| eye7 | number \| null | 从左到右第 7 段宽度（cm）：右脸颊 → 人头最右（右耳外侧段）。该侧耳朵不可见时为 null |

> `eye1`~`eye7` 为从左到右共 7 段宽度，与标注图竖线一一对应。最左/最右端线取自耳朵分割外缘；某侧耳朵被头发或侧脸遮挡（不可见）时该侧端线省略，对应 `eye1` 或 `eye7` 为 `null`（键始终保留），实际有效段为 5 或 6 段。`eye3`/`eye5` 为左右眼宽、`eye4` 为两眼间距，与 `eye_width_cm` / `inter_eye_distance_cm` 语义一致。

### 标注图片（UI）规范

| 项目 | 要求 |
|------|------|
| 颜色 | 字体及所有线/箭头 `#FFFFFF` 100%，透明底 |
| 尺寸 | 字号/线宽/虚线/箭头按图片**短边自适应缩放**（非固定 pt） |
| 横线 | 5 条分界线（头顶/发际线/眉心/鼻翼下缘/下巴尖），两端渐变消失并略超出最外侧竖线；线名在线**右上方** |
| 竖线 | 人头最左 + 七眼 6 点 + 人头最右（最外两条取自头发分割轮廓），两端渐变消失并略超出头顶/下巴 |
| 数值排布 | 四庭数值（名 + 数值两行，**不带 cm**）统一在图片**左侧**呈现；七眼段宽**上下穿插**展示；底部统一标「单位cm」 |
| 线样式 | 段宽/庭高用**虚线 + 实心三角双箭头**标示（箭头尖端落在虚线两端） |

### 响应示例（当前 Mock 返回值）

```json
{
  "code": 0,
  "message": "success",
  "request_id": "mock-request-id",
  "data": {
    "annotated_image_url": "https://hair.xiangsilian.com/static/sample.jpg",
    "face_total_height_cm": 13.76,
    "four_courts": {
      "top_court_cm": 3.44,
      "upper_court_cm": 3.44,
      "middle_court_cm": 3.44,
      "lower_court_cm": 3.44,
      "ratios": { "top_court": 0.25, "upper_court": 0.25, "middle_court": 0.25, "lower_court": 0.25 }
    },
    "seven_eyes": {
      "eye_width_cm": 3.44,
      "face_width_cm": 24.08,
      "inter_eye_distance_cm": 3.44,
      "ratios": { "eye_width": 0.143, "inter_eye_distance": 0.143 },
      "eye1": 3.44, "eye2": 3.44, "eye3": 3.44, "eye4": 3.44,
      "eye5": 3.44, "eye6": 3.44, "eye7": 3.44
    },
    "landmarks": {
      "hair_top": { "x": 540, "y": 120 },
      "hairline": { "x": 540, "y": 430 },
      "brow_center": { "x": 540, "y": 740 },
      "nose_bottom": { "x": 540, "y": 1050 },
      "chin_tip": { "x": 540, "y": 1360 }
    }
  }
}
```

---

## 接口 6：四庭七眼测量 v2 接口

**说明**：基于[接口 1](#接口-1四庭七眼测量标注接口)的变体。与接口 1 的差异：

- **去顶庭**：不画头顶横线、不返回顶庭数据。`four_courts` 仅含上/中/下庭，`landmarks` 无 `hair_top`，`face_total_height_cm` 为三庭之和（不含顶庭）。
- **竖线范围**：纵向竖线从**发际线**画到**下巴尖**（接口 1 为头顶→下巴尖）。
- **不画人头最左/最右端线**：仅画七眼 6 点（左脸颊/左眼外角/左眼内角/右眼内角/右眼外角/右脸颊）共 5 段标尺，不取头发轮廓的头部端线（接口 1 会多出最左/最右 2 条头部端线、共 7 段）。
- 其余（实心三角箭头、虚线样式、字体、单位cm、七眼数据）与接口 1 一致。

**请求**：`POST /api/v1/face/measure-v2`

### 输入

与接口 1 完全相同。图片参数见「通用约定 → 图片传参字段」（`image_file` / `image_url` / `image_base64` 三选一）。本接口无其他专属参数。

### 输出（data）

| 字段 | 类型 | 说明 |
|------|------|------|
| annotated_image_url | string | 标注图层 PNG URL（透明底，仅标注线/文字，不含人物） |
| face_total_height_cm | number | 面部总高度（cm）= 上庭 + 中庭 + 下庭（**不含顶庭**） |
| four_courts | object | 三庭数据（上/中/下庭，各含 cm 与 ratio；**无顶庭**） |
| seven_eyes | object | 七眼数据（眼宽/脸宽/两眼间距，各含 cm 与 ratio） |
| landmarks | object | 四个关键点像素坐标（发际线/眉心/鼻翼下缘/下巴尖） |

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "request_id": "mock-request-id",
  "data": {
    "annotated_image_url": "https://hair.xiangsilian.com/static/sample.jpg",
    "face_total_height_cm": 10.32,
    "four_courts": {
      "upper_court_cm": 3.44, "middle_court_cm": 3.44, "lower_court_cm": 3.44,
      "ratios": { "upper_court": 0.333, "middle_court": 0.333, "lower_court": 0.333 }
    },
    "seven_eyes": {
      "eye_width_cm": 3.44, "face_width_cm": 24.08, "inter_eye_distance_cm": 3.44,
      "ratios": { "eye_width": 0.143, "inter_eye_distance": 0.143 }
    },
    "landmarks": {
      "hairline": { "x": 540, "y": 430 },
      "brow_center": { "x": 540, "y": 740 },
      "nose_bottom": { "x": 540, "y": 1050 },
      "chin_tip": { "x": 540, "y": 1360 }
    }
  }
}
```

---

## 接口 2：C 端生发接口

**说明**：输入用户正面照 + 性别 + 发型序号（可多选），按指定发际线类型渲染发际线曲线透明 PNG + 生发图。

> **每个方案返回两张图**：`image_url`=「发际线曲线**透明 PNG**（仅白色曲线，透明底，需叠加原图显示）」；`grown_image_url`=
> 经 ComfyUI/Flux 的「植发 3 个月**生发后图片**」（完整人像照片）。两者均已实现，实现简述见 [`实现说明.md`](实现说明.md)。

**请求**：`POST /api/v1/hair/grow`

### 输入

图片参数见「通用约定 → 图片传参字段」。专属参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 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` 时用干净原图生成（空遮罩、不烧模板黑线），供测试对比 |

### 输出（data）

`results`：发际线方案数组，**数量 = 所选发型数**。每个元素：

| 字段 | 类型 | 说明 |
|------|------|------|
| image_url | string | 发际线曲线**透明 PNG** URL（仅白色发际线曲线，透明底，**不含人物**，需前端叠加原图显示） |
| grown_image_url | string | **生发后图片** URL（ComfyUI/Flux「植发 3 个月」效果图，完整人像照片） |
| hairline_type | string | 发际线类型 key：`ellipse`/`flower`/`heart`/`straight`/`wave`（female），`ellipse`/`m`/`straight`/`inverse_arc`（male） |
| order | int | 排序序号（当前阶段固定 `1..N`，按贴图顺序，暂不计算合适度） |

> ⚠️ 生发图由本机 ComfyUI（Flux-2，端口 8182）生成，**一次请求生成指定发型的 1 张、同步返回**。
> worker 侧返回 `image_base64` / `grown_image_base64`，
> 网关落盘后改写为上表的 `image_url` / `grown_image_url`。
>
> 💡 `image_url` 为透明底 PNG，前端需用绝对定位叠加到原图上显示（参考[测试页](https://hair.xiangsilian.com/static/test_interface2.html)的 `.img-stack` 叠加结构）。

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "request_id": "mock-request-id",
  "data": {
    "results": [
      { "image_url": "https://hair.xiangsilian.com/static/annotations/uuid1.png", "grown_image_url": "https://hair.xiangsilian.com/static/annotations/grown1.png", "hairline_type": "ellipse", "order": 1 },
      { "image_url": "https://hair.xiangsilian.com/static/annotations/uuid2.png", "grown_image_url": "https://hair.xiangsilian.com/static/annotations/grown2.png", "hairline_type": "flower", "order": 2 }
    ]
  }
}
```

> 识别失败时返回通用错误码（1001 / 1002 / 1003 等）。`gender` 缺失或非法值返回 **1004**；本接口已改为必填入参，不再自动判别性别。

---

## 接口 3：B 端生发接口

**说明**：医生/操作端在用户照片上用马克笔标注目标发际线后，**只需上传这一张划线图**。系统检测划线 →
据此生成生发后图片。

**请求**：`POST /api/v1/hair/grow-b`

### 输入

划线图片支持「文件 / URL / base64」三选一（字段：`marked_image_file` / `marked_image_url` / `marked_image_base64`）。
**不需要原始照片**（划线图本身就是用户照片 + 手绘线）。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| marked_image_* | file / string | 是 | 已用马克笔标注发际线的图片，三选一 |
| use_mask | bool | 否 | 是否画发际线，默认 `true`。`false` 时跳过划线检测、直接送划线图，模型仅凭手绘黑线生发，供测试对比 |

### 输出（data）

| 字段 | 类型 | 说明 |
|------|------|------|
| hair_growth_image_url | string | **生发后图片**（检测划线 → ComfyUI/Flux「植发 3 个月」效果）。worker 返回 `hair_growth_image_base64` |
| hairline_type | string | 发际线形，手绘为定制，固定 `"custom"` |

> 未检测到划线（或无人脸）返回 **1001**。

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "request_id": "mock-request-id",
  "data": {
    "hair_growth_image_url": "https://hair.xiangsilian.com/static/annotations/grown.png",
    "hairline_type": "custom"
  }
}
```

---

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

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

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

### 输入

图片参数见「通用约定 → 图片传参字段」。本接口无其他专属参数。

### 输出（data）

`data.features` 是一个 **JSON 字符串**（不是对象，客户端 `JSON.parse()` 后用），**仅含以下 6 个英文字段**：

| 字段 | 说明 |
|------|------|
| face_shape | 脸形（脸型）|
| eyebrow_shape | 眉形 |
| facial_age | 面部年龄（区间字符串，如"18-25岁"）|
| dynamic_static_type | 动静类型（静态型/动态型）|
| gender | 性别（男/女）|
| gene_style | 基因风格（如"自然型"）|

> 无人脸返回 `1001`（据 doubao「图片是否有人脸」判定）。⚠️ 本接口是唯一调**外网云模型**的接口，
> worker 需可访问 `ark.cn-beijing.volces.com`；API Key 走 worker 配置/环境变量。

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "request_id": "mock-request-id",
  "data": {
    "features": "{\"face_shape\":\"鹅蛋脸\",\"eyebrow_shape\":\"平眉\",\"facial_age\":\"18-25岁\",\"dynamic_static_type\":\"静态型\",\"gender\":\"女\",\"gene_style\":\"少年型\"}"
  }
}
```

> `features` 为字符串形式的 JSON，固定上述 6 个字段。

---

## 接口 5：发际线 PNG 生成接口

**说明**：入参同接口2（先选性别、再多选发型）。对每个选中发型返回 `middle` / `high` / `low` **三档**发际线叠图与**生发图**，并返回「最合适发际线」的面部中间点坐标。

**请求**：`POST /api/v1/hairline/generate`

### 输入

图片参数见「通用约定 → 图片传参字段」。专属参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| gender | string | **是** | 性别：`male` / `female`。决定发型集合（female 5 / male 4）。缺失/非法返回 `1004` |
| 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 的文本 |

> ⚠️ 三档叠图分别用 `hairline_texture` / `hairline_texture_high` / `hairline_texture_low` 三套同名贴图；**生发黑模板固定取自 `hairline_texture_black/`（middle 档）**，即生发目标固定压到 middle 档，每个发型仅 1 张生发图。

### 输出（data）

| 字段 | 类型 | 说明 |
|------|------|------|
| hairline_images | object[] | **选中发型**列表，**数量 = 所选发型数**，元素见下表 |
| best_hairline_center_point | object | **首个选中发型**的 middle 档发际线曲线「面部中间点」坐标，原图像素：`{ "x": number, "y": number }` |
| face_measure | object \| null | **复用接口1**的四庭七眼测量**数值**（不含标注图）。独立流程，测量失败（无人脸/非正面/分割失败）时为 `null`，不影响发际线主结果。字段结构见下表 |

`hairline_images` 元素：

| 字段 | 类型 | 说明 |
|------|------|------|
| hairline_type | string | 发际线类型 key：`ellipse`/`flower`/`heart`/`straight`/`wave`（female），`ellipse`/`m`/`straight`/`inverse_arc`（male） |
| 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`） |
| order | int | 发型序号（= 传入的 hair_style 值） |

> worker 侧返回 `image_middle_base64` / `image_high_base64` / `image_low_base64` / `grown_image_base64`，网关落盘后改写为上表对应的 `*_url`。
>
> 💡 三档 `image_*_url` 为透明底 PNG，前端需用绝对定位叠加到原图上显示（参考[测试页](https://hair.xiangsilian.com/static/test_interface5.html)的 `.img-stack` 叠加结构）。`grown_image_url` 是完整人像照片，直接显示即可。

`face_measure` 元素（与[接口1](#接口-1四庭七眼测量标注接口)的 `data` 同构，**不含** `annotated_image_*` 标注图字段）：

| 字段 | 类型 | 说明 |
|------|------|------|
| face_total_height_cm | number | 全脸总高度（cm）= 四庭之和 |
| four_courts | object | 四庭数据（顶/上/中/下庭 cm + 占比 ratios），结构同接口1 |
| seven_eyes | object | 七眼数据（眼宽/脸宽/两眼间距 cm + 占比 ratios + eye1~eye7 从左到右 7 段宽度），结构同接口1 |
| landmarks | object | 5 个纵向关键点像素坐标（hair_top/hairline/brow_center/nose_bottom/chin_tip），结构同接口1 |
| hairline_source | string | 发际线来源：`segmentation`（真实分割）/ `estimated`（比例估算） |
| head_pose | object | 头部姿态角度（yaw/pitch/roll，单位：度） |

> `eye1`~`eye7` 为从左到右共 7 段宽度，eye1=左耳外段、eye7=右耳外段，某侧耳朵不可见时对应段为 `null`。详见接口1说明。

### 响应示例（当前 Mock 返回值）

```json
{
  "code": 0,
  "message": "success",
  "request_id": "mock-request-id",
  "data": {
    "hairline_images": [
      {
        "hairline_type": "ellipse",
        "image_middle_url": "https://hair.xiangsilian.com/static/annotations/mid1.png",
        "image_high_url": "https://hair.xiangsilian.com/static/annotations/high1.png",
        "image_low_url": "https://hair.xiangsilian.com/static/annotations/low1.png",
        "grown_image_url": "https://hair.xiangsilian.com/static/annotations/grown1.png",
        "order": 1
      },
      {
        "hairline_type": "heart",
        "image_middle_url": "https://hair.xiangsilian.com/static/annotations/mid3.png",
        "image_high_url": "https://hair.xiangsilian.com/static/annotations/high3.png",
        "image_low_url": "https://hair.xiangsilian.com/static/annotations/low3.png",
        "grown_image_base64": null,
        "order": 3
      }
    ],
    "best_hairline_center_point": { "x": 540, "y": 430 },
    "face_measure": {
      "face_total_height_cm": 26.76,
      "four_courts": {
        "top_court_cm": 5.77, "upper_court_cm": 5.93,
        "middle_court_cm": 7.62, "lower_court_cm": 7.44,
        "ratios": { "top_court": 0.216, "upper_court": 0.222,
                    "middle_court": 0.285, "lower_court": 0.278 }
      },
      "seven_eyes": {
        "eye_width_cm": 2.76, "face_width_cm": 15.08,
        "inter_eye_distance_cm": 3.9,
        "ratios": { "eye_width": 0.183, "inter_eye_distance": 0.259 },
        "eye1": null, "eye2": 3.0, "eye3": 2.76, "eye4": 3.9,
        "eye5": 2.76, "eye6": 3.0, "eye7": null
      },
      "landmarks": {
        "hair_top": { "x": 504, "y": 103 },
        "hairline": { "x": 504, "y": 228 },
        "brow_center": { "x": 504, "y": 357 },
        "nose_bottom": { "x": 505, "y": 522 },
        "chin_tip": { "x": 506, "y": 683 }
      },
      "hairline_source": "segmentation",
      "head_pose": { "yaw": -1.39, "pitch": 2.49, "roll": -0.06 }
    }
  }
}
```

> 说明：生发失败的元素中，网关不改写 `null` 值，故字段名保持为 `grown_image_base64: null`（有值时才改写为 `grown_image_url`），与接口2生发失败项一致。

---

## 接口 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` 时用干净原图生成（空遮罩、不烧模板黑线） |

### 输出（data）

与接口 2 完全相同。`results`：发际线方案数组，**数量 = 所选发型数**。每个元素：

| 字段 | 类型 | 说明 |
|------|------|------|
| 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（无人物）+ 四庭/七眼厘米数值与坐标 |
| 6 四庭七眼测量 v2 | 用户照片 | 同接口1，复刻实现 |
| 2 C 端生发 | 用户照片 | 生发后图片 + 指定发际线预览（单/多张） |
| 3 B 端生发 | 划线图片 | 最合适发际线图片 + 生发后图片 |
| 4 用户特征 | 用户照片 | 6 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格） |
| 5 发际线 PNG | 用户照片 + gender + hair_style（多选） | 每个选中发型 middle/high/low 三档发际线叠图 + 生发图 + 最合适发际线面部中间点坐标 |
| 7 C 端生发 v2 | 用户照片 + gender + hair_style | 同接口2，使用 add_hair2.json 工作流 |

---

## 已确认结论

- 图片传参：**文件 / URL / base64 三种都支持，严格互斥**（必须且只能传一个，base64 需带 `data:image/...;base64,` 前缀）。
- 默认单人；检测到 2~3 人报错提示客户端；单文件 **≤ 1 MB**；格式仅 **JPG / PNG**。
- 所有坐标基准：**原图像素**。
- 接口 2：提供「美颜」开关 `beauty_enabled`。
- 接口 3：需同时上传原图，需返回发际线类型。
- 接口 4：`data` 返回**一个 JSON 字符串**，字段不固定，可随时调整。
- 接口 5：发际线 PNG 数量 **N 不固定**，需按合适度**排序**。
- 英文字段命名由本文档约定（见各接口表格）。

## 待与需求方确认的问题清单

1. 接口 1 标注图片设计稿（见下方说明）。