371 lines
13 KiB
Markdown
371 lines
13 KiB
Markdown
# 旷视五个接口 — 接口文档（输入 / 输出定义）
|
||
|
||
> 本文档依据《旷视具体需求.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` |
|
||
| 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` |
|
||
|
||
---
|
||
|
||
## 通用约定
|
||
|
||
以下约定适用于全部 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 | 性别标签判断异常 | 男女标签无法判定 **【待确认】** 是否作为错误 |
|
||
| 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 | 七眼各段占脸宽的比例 |
|
||
|
||
### 标注图片（UI）规范
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| 字体及线颜色 | `#FFFFFF` 100% |
|
||
| 数值排布 | 四庭数值统一在图片**左侧**呈现；七眼间距**上下穿插**展示 |
|
||
| 字体 | PingFangSC-Regular，字号 10pt |
|
||
| 线宽 | 横线、竖线、虚线均为 1pt |
|
||
| 线样式 | 横线、竖线渐变消失；虚线两侧呈现箭头 |
|
||
|
||
> **【待确认】** 标注图片需提供设计稿后才能最终确定样式。
|
||
|
||
### 响应示例（当前 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 }
|
||
},
|
||
"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 }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口 2：C 端生发接口
|
||
|
||
**说明**：输入用户正面照，输出生发后的图片，以及推荐的发际线（可能多张），并按合适度排序。
|
||
|
||
**请求**：`POST /api/v1/hair/grow`
|
||
|
||
### 输入
|
||
|
||
图片参数见「通用约定 → 图片传参字段」。专属参数：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| beauty_enabled | bool | 否 | 生发图是否带美颜效果，默认 false。提供该开关 |
|
||
|
||
### 输出（data）
|
||
|
||
`results`：发际线方案数组（可能多张），每个元素：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| image_url | string | 生发后图片 URL |
|
||
| hairline_type | string | 图片对应的发际线形（如：花瓣形、波浪形） |
|
||
| order | int | 排序序号（1 = 最优，2 次之 …） |
|
||
|
||
### 响应示例（当前 Mock 返回值）
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"request_id": "mock-request-id",
|
||
"data": {
|
||
"results": [
|
||
{ "image_url": "https://hair.xiangsilian.com/static/sample.jpg", "hairline_type": "花瓣形", "order": 1 },
|
||
{ "image_url": "https://hair.xiangsilian.com/static/sample.jpg", "hairline_type": "波浪形", "order": 2 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> 识别失败时返回通用错误码（1001 / 1002 / 1003 等）。
|
||
|
||
---
|
||
|
||
## 接口 3：B 端生发接口
|
||
|
||
**说明**：输入医生/操作端的「划线图片」（在原图上标注了目标发际线），输出最合适的发际线图片 + 生发后图片。
|
||
|
||
**请求**：`POST /api/v1/hair/grow-b`
|
||
|
||
### 输入
|
||
|
||
划线图片同样支持「文件 / URL / base64」三种方式（字段：`marked_image_file` / `marked_image_url` / `marked_image_base64`）。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| marked_image_* | file / string | 是 | 已划线（标注发际线）的图片，三选一 |
|
||
| original_image_* | file / string | 是 | 原始用户照片，需同时上传 |
|
||
|
||
### 输出（data）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| best_hairline_image_url | string | 最合适的发际线图片 |
|
||
| hair_growth_image_url | string | 生发后图片 |
|
||
| hairline_type | string | 发际线形，需返回 |
|
||
|
||
### 响应示例（当前 Mock 返回值）
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"request_id": "mock-request-id",
|
||
"data": {
|
||
"best_hairline_image_url": "https://hair.xiangsilian.com/static/sample.jpg",
|
||
"hair_growth_image_url": "https://hair.xiangsilian.com/static/sample.jpg",
|
||
"hairline_type": "花瓣形"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口 4：用户特征接口
|
||
|
||
**说明**：输入用户照片，输出 N 个用户特征字段。
|
||
|
||
**请求**：`POST /api/v1/face/features`
|
||
|
||
### 输入
|
||
|
||
图片参数见「通用约定 → 图片传参字段」。本接口无其他专属参数。
|
||
|
||
### 输出（data）
|
||
|
||
`data` 直接返回一个 **JSON 字符串**（`features`），其内部字段不固定、可随时调整，由业务方约定。当前优先返回的字段如下（仅作示例，最终以实际返回为准）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| face_shape | string | 脸形 |
|
||
| eyebrow_shape | string | 眉形 |
|
||
| facial_age | int | 面部年龄 |
|
||
| dynamic_static_type | string | 动静类型 |
|
||
| gender | string | 性别 |
|
||
| gene_style | object | 面部特征对应面部标签的「基因风格」 |
|
||
|
||
### 响应示例（当前 Mock 返回值）
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"request_id": "mock-request-id",
|
||
"data": {
|
||
"features": "{\"face_shape\": \"鹅蛋脸\", \"eyebrow_shape\": \"柳叶眉\", \"facial_age\": 26, \"dynamic_static_type\": \"静态\", \"gender\": \"女\", \"gene_style\": {\"label\": \"面部特征标签\", \"style\": \"基因风格示例\"}}"
|
||
}
|
||
}
|
||
```
|
||
|
||
> `features` 为字符串形式的 JSON，字段后续可随时增删，不固定。
|
||
|
||
---
|
||
|
||
## 接口 5：发际线 PNG 生成接口
|
||
|
||
**说明**：输入用户照片，返回 N 张用户发际线的 PNG 图片，并返回「最合适发际线」的面部中间点坐标。
|
||
|
||
**请求**：`POST /api/v1/hairline/generate`
|
||
|
||
### 输入
|
||
|
||
图片参数见「通用约定 → 图片传参字段」。本接口无其他专属参数。
|
||
|
||
### 输出（data）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| hairline_images | object[] | N 张用户发际线 PNG，**数量 N 不固定**，已按合适度排序，元素见下表 |
|
||
| best_hairline_center_point | object | 最合适发际线的「面部中间点」坐标，原图像素：`{ "x": number, "y": number }` |
|
||
|
||
`hairline_images` 元素：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| image_url | string | 发际线 PNG 图片 URL |
|
||
| order | int | 排序序号（1 = 最合适，依次递增） |
|
||
|
||
### 响应示例（当前 Mock 返回值）
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"request_id": "mock-request-id",
|
||
"data": {
|
||
"hairline_images": [
|
||
{ "image_url": "https://hair.xiangsilian.com/static/sample.jpg", "order": 1 },
|
||
{ "image_url": "https://hair.xiangsilian.com/static/sample.jpg", "order": 2 }
|
||
],
|
||
"best_hairline_center_point": { "x": 540, "y": 430 }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 汇总：输入输出一览
|
||
|
||
| 接口 | 输入 | 主要输出 |
|
||
|------|------|----------|
|
||
| 1 四庭七眼测量 | 用户照片 | 标注 PNG（无人物）+ 四庭/七眼厘米数值与坐标 |
|
||
| 2 C 端生发 | 用户照片 | 生发后图片 + 多张发际线（带类型与排序） |
|
||
| 3 B 端生发 | 划线图片 | 最合适发际线图片 + 生发后图片 |
|
||
| 4 用户特征 | 用户照片 | N 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格…） |
|
||
| 5 发际线 PNG | 用户照片 | N 张发际线 PNG + 最合适发际线面部中间点坐标 |
|
||
|
||
---
|
||
|
||
## 已确认结论
|
||
|
||
- 图片传参：**文件 / URL / base64 三种都支持，严格互斥**（必须且只能传一个，base64 需带 `data:image/...;base64,` 前缀）。
|
||
- 默认单人；检测到 2~3 人报错提示客户端；单文件 **≤ 1 MB**；格式仅 **JPG / PNG**。
|
||
- 所有坐标基准：**原图像素**。
|
||
- 接口 2：提供「美颜」开关 `beauty_enabled`。
|
||
- 接口 3：需同时上传原图，需返回发际线类型。
|
||
- 接口 4：`data` 返回**一个 JSON 字符串**，字段不固定，可随时调整。
|
||
- 接口 5：发际线 PNG 数量 **N 不固定**，需按合适度**排序**。
|
||
- 英文字段命名由本文档约定（见各接口表格）。
|
||
|
||
## 待与需求方确认的问题清单
|
||
|
||
1. 接口 1 标注图片设计稿（见下方说明）。
|