From bee4bdae107ddf4dcd5a8d0a685b66ff39313e7a Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Mon, 15 Jun 2026 21:26:56 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=89=8D=E7=AB=AF=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E9=A1=B5=20+=20=E7=BD=91=E5=85=B3=E9=A6=96?= =?UTF-8?q?=E9=A1=B5=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - static/integration.html: 5接口入参/出参表、fetch示例、错误码、在线测试页链接 - gateway/app.py: 首页 / 增加 test_pages 和 integration_guide 索引 --- gateway/app.py | 10 +- static/integration.html | 277 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 285 insertions(+), 2 deletions(-) create mode 100644 static/integration.html diff --git a/gateway/app.py b/gateway/app.py index 076365b..5e60079 100644 --- a/gateway/app.py +++ b/gateway/app.py @@ -185,11 +185,17 @@ async def health(): @app.get("/", include_in_schema=False) async def index(): - cfg = load_config() return { "service": "旷视五接口 — 网关", "version": "0.1.0", - "docs": f"{cfg['public_base_url']}/docs", + "docs": "/docs", + "integration_guide": "/static/integration.html", + "test_pages": { + "if1_measure": "/static/test_interface1.html", + "if2_hair_grow": "/static/test_interface2.html", + "if3_hair_grow_b": "/static/test_interface3.html", + "if5_hairline": "/static/test_interface5.html", + }, } diff --git a/static/integration.html b/static/integration.html new file mode 100644 index 0000000..3f9d0c0 --- /dev/null +++ b/static/integration.html @@ -0,0 +1,277 @@ + + + + + +旷视五接口 — 前端接入说明 + + + +
+

📡 旷视五接口 — 前端接入说明

+

Base URL: https://hair.xiangsilian.com  |  在线文档: /docs  |  在线测试页见底部

+ +
+ 通用约定 + 接口1 + 接口2 + 接口3 + 接口4 + 接口5 + 错误码 + 在线测试 +
+ + +
+

🔧 通用约定

+
+ + + + + + + +
协议HTTPS
请求方式全部 POST
编码UTF-8
Content-Typemultipart/form-data
图片参数三选一：image_file（文件上传）/ image_url（URL）/ image_base64（base64 + 前缀）
图片格式JPG / PNG，≤ 1 MB，单人正面照
+ +

统一响应结构：

+ 
{
+  "code": 0,           // 0=成功，非0=错误
+  "message": "success",
+  "request_id": "...",  // 请求追踪 ID
+  "data": { ... }       // 业务数据，各接口不同
+}
+
+
+ + +
+

1. 四庭七眼测量  POST  /api/v1/face/measure

+
+

上传正面照 → 返回标注好的 PNG（仅标注图层，透明底）+ 四庭七眼厘米数值 + 关键点像素坐标。

+ +

入参

+ + + + + +
参数类型必填说明
image_filefile三选一上传图片文件
image_urlstring三选一图片 URL
image_base64string三选一base64 字符串，需带 data:image/...;base64, 前缀
+ +

data 字段

+ + + + + + + +
字段类型说明
annotated_image_urlstring标注 PNG URL（仅标注图层，透明底，叠加到原图上显示）
face_total_height_cmnumber全脸高度（cm）
four_courtsobject四庭：top/upper/middle/lower，各含 _cm 和 ratios
seven_eyesobject七眼：eye_width/face_width/inter_eye_distance，各含 _cm 和 ratios
landmarksobject5 个关键点像素坐标：hair_top/hairline/brow_center/nose_bottom/chin_tip
+ +

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

+ +

请求示例（fetch）：

+ 
const fd = new FormData();
+fd.append('image_file', file);  // 或 image_url / image_base64
+
+const res = await fetch('https://hair.xiangsilian.com/api/v1/face/measure', {
+  method: 'POST',
+  body: fd
+});
+const { code, data } = await res.json();
+// data.annotated_image_url  →  标注 PNG
+// data.face_total_height_cm  →  全脸高度
+// data.four_courts.ratios    →  { top_court: 0.25, ... }
+// 前端叠加显示：原图 + annotated_image_url（absolute 叠加）
+
+
+ + +
+

2. C端生发  POST  /api/v1/hair/grow

+
+

上传正面照 + 性别 → 多组发际线方案。每组含发际线叠加预览图 + ComfyUI 生发效果图。

+ +

入参

+ + + + +
参数类型必填说明
image_file / image_url / image_base64—三选一用户正面照
genderstring✅ 必填"male" / "female"
+ +

data.results[] 元素

+ + + + + + +
字段类型说明
image_urlstring发际线叠加预览图（曲线叠在原图上）
grown_image_urlstring生发后效果图（ComfyUI/Flux「植发3个月」）⚠ 可空
hairline_typestring发际线类型 key
orderint排序（1=最佳，当前按贴图顺序）
+ +

+ Female 5 种：ellipse/flower/heart/straight/wave  |  + Male 4 种：ellipse/m/straight/inverse_arc
+ ⚠ 生发图由本机 ComfyUI 生成，耗时可达数分钟，fetch 超时需放大（≥5min）。 +

+
+
+ + +
+

3. B端生发（医生端） POST  /api/v1/hair/grow-b

+
+

医生用马克笔在用户照片额头画线 → 拍照上传 → 系统生成生发效果图。

+ +

入参

+ + + +
参数类型必填说明
marked_image_file / marked_image_url / marked_image_base64—✅ 三选一已用马克笔标注发际线的图片
+ +

data 字段

+ + + + +
字段类型说明
hair_growth_image_urlstring生发后效果图 URL ⚠ 可空
hairline_typestring固定 "custom"（手绘定制）
+ +

⚠ 划线图未检测到划线（或无人脸）→ code=1001

+
+
+ + +
+

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

+
+

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

+ +

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

+ +

data 字段

+ + + +
字段类型说明
featuresstringJSON 字符串（不是对象！客户端需 JSON.parse()）
+ +

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

+ + + + + +
字段说明字段说明
face_shape脸型eyebrow_shape眉形
facial_age面部年龄区间gender性别
dynamic_static_type动静类型gene_style基因风格
+ + 
const res = await fetch('https://hair.xiangsilian.com/api/v1/face/features', {
+  method: 'POST',
+  body: fd
+});
+const { code, data } = await res.json();
+const features = JSON.parse(data.features);  // ← 注意：data.features 是字符串！
+console.log(features.face_shape);   // "鹅蛋脸"
+console.log(features['四季色彩季型']); // "冷夏型"（中文字段也保留）
+
+
+ + +
+

5. 发际线 PNG 生成  POST  /api/v1/hairline/generate

+
+

上传正面照 + 性别 → N 张发际线叠加图 + 最佳发际线中心点坐标。

+ +

入参

+ + + + +
参数类型必填说明
image_file / image_url / image_base64—三选一用户正面照
genderstring✅ 必填"male" / "female"
+ +

data 字段

+ + + + +
字段类型说明
hairline_images[]object[]发际线叠加图列表，每项含 image_url + order
best_hairline_center_pointobject最佳发际线中心点像素坐标 { x: number, y: number }
+
+
+ + +
+

⚠ 错误码

+
+ + + + + + + + + +
codemessage说明
1001无法识别人像未检测到人脸
1002人像分辨率过低低于最低分辨率
1003角度问题，非正面照非正面 / 角度过大
1005检测到多张人脸仅支持单人
1006文件超出大小限制单文件 > 1 MB
1007图片参数错误 / 后端不可用参数传错 / 服务繁忙请稍后重试
1008图片格式不支持非 JPG/PNG / base64 解码失败
+

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

+
+
+ + +
+

🧪 在线测试页面

+
+ + + + + + +
接口测试页功能
1. 四庭七眼/static/test_interface1.html上传照片 → 原图+标注叠加，底图/标注开关，指标卡片
2. C端生发/static/test_interface2.html上传+性别 → 方案一覧（原图/叠加/生发），双图对比
3. B端生发/static/test_interface3.html划线图上传 → 生发效果图
5. 发际线PNG/static/test_interface5.html上传+性别 → 发际线方案+中心点坐标
+

+ 接口4 无测试页（纯 JSON 返回特征字段，浏览器直接调即可查看）。 + 完整 API 文档：/docs（Swagger UI） +

+
+
+ +

+ Base: https://hair.xiangsilian.com  |  Swagger: /docs  |  接入说明: /static/integration.html +

+
+ +