"""旷视五接口 - 第一版（Mock 实现） 当前为 Mock 服务，所有接口返回固定示例值，不做真实算法计算。 图片字段统一返回 https://hair.xiangsilian.com/static/sample.jpg。 """ import json from typing import Any, List, Optional from fastapi import FastAPI, File, Form, UploadFile from fastapi.staticfiles import StaticFiles from pydantic import BaseModel, Field # --------------------------------------------------------------------------- # App & 全局常量 # --------------------------------------------------------------------------- BASE_URL = "https://hair.xiangsilian.com" SAMPLE_IMAGE_URL = f"{BASE_URL}/static/sample.jpg" app = FastAPI( title="旷视五接口", version="0.1.0", description=""" ## 概述 本服务提供五个人像分析接口，当前为 **Mock 第一版**： - 接口已全部上线，传任意合法参数均可正常响应 - 所有字段返回固定示例值，图片字段统一指向示例图片 - 真实算法逻辑后续接入，字段结构不变 ## 图片传参说明 每个接口的图片参数均支持三种方式，**严格互斥，必须且只能选其一**： | 方式 | 字段名 | 说明 | |------|--------|------| | 文件上传 | `image_file` | `multipart/form-data`，单文件 ≤ 1 MB | | URL | `image_url` | 图片的完整 HTTP/HTTPS 地址 | | base64 | `image_base64` | 需携带前缀，如 `data:image/jpeg;base64,xxxx` | > 传 0 个或同时传多个，均返回错误码 `1007`。 ## 图片要求 - 格式：**JPG / PNG** - 分辨率：最低 1080×1920，最大 4000×5000 - 人脸数量：仅支持**单人**，多人返回错误码 `1005` - 文件大小：≤ 1 MB（文件上传方式） ## 统一响应结构 ```json { "code": 0, "message": "success", "request_id": "唯一请求标识", "data": {} } ``` `code = 0` 表示成功，非 0 表示失败，`message` 为具体原因。 ## 错误码一览 | code | 说明 | |------|------| | 1001 | 无法识别人像 | | 1002 | 人像分辨率过低 | | 1003 | 非正面照 / 角度过大 | | 1004 | 性别标签无法判定 | | 1005 | 检测到多张人脸（仅支持单人）| | 1006 | 文件超出 1 MB 限制 | | 1007 | 图片参数错误（未传或同时传多个）| | 1008 | 图片格式不支持（仅 JPG / PNG）| """, ) app.mount("/static", StaticFiles(directory="static"), name="static") # --------------------------------------------------------------------------- # 通用响应模型 # --------------------------------------------------------------------------- def ok(data: Any) -> dict: return { "code": 0, "message": "success", "request_id": "mock-request-id", "data": data, } def err(code: int, message: str) -> dict: return { "code": code, "message": message, "request_id": "mock-request-id", "data": None, } # --------------------------------------------------------------------------- # 通用图片请求 Body（JSON 方式，用于 url / base64） # --------------------------------------------------------------------------- _image_fields_desc = ( "图片传参方式严格互斥，必须且只能选其一：\n" "- **image_file**（multipart/form-data 上传，≤ 1 MB）\n" "- **image_url**（完整 HTTP/HTTPS 地址）\n" "- **image_base64**（需携带前缀，如 `data:image/jpeg;base64,xxxx`）\n\n" "同时传多个或一个都不传，均返回错误码 `1007`。" ) class ImageJsonBody(BaseModel): image_url: Optional[str] = Field( default=None, description="图片 URL（与 image_base64 二选一，不可同时传）", examples=["https://hair.xiangsilian.com/static/sample.jpg"], ) image_base64: Optional[str] = Field( default=None, description="图片 base64，需带前缀，如 `data:image/jpeg;base64,xxxx`", examples=["data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."], ) model_config = { "json_schema_extra": { "examples": [ { "summary": "使用 URL 传图", "value": {"image_url": "https://hair.xiangsilian.com/static/sample.jpg"}, }, { "summary": "使用 base64 传图", "value": {"image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."}, }, ] } } # --------------------------------------------------------------------------- # 接口 1：四庭七眼测量标注 # --------------------------------------------------------------------------- @app.post( "/api/v1/face/measure", summary="接口1 四庭七眼测量标注", tags=["人脸分析"], description=f""" 输入用户正面照，返回： - 标注好四庭七眼数据的 **PNG 图片**（仅标注图层，不含人物） - 四庭（顶庭/上庭/中庭/下庭）各段**厘米数值及占比** - 七眼（眼宽/脸宽/两眼间距）**厘米数值及占比** - 五个关键分界点的**原图像素坐标**（头顶/发际线/眉心/鼻翼下缘/下巴尖） {_image_fields_desc} 图片同时支持 `multipart/form-data` 文件上传（字段名 `image_file`），或 JSON Body 传 `image_url` / `image_base64`。 --- **坐标说明**：所有坐标以原图像素为基准，原点为图片左上角，x 向右，y 向下。 **标注图片 UI 规范**（真实版本生效）： - 字体/线条颜色：`#FFFFFF 100%` - 四庭数值在图片**左侧**呈现，七眼间距**上下穿插**展示 - 字体：PingFangSC-Regular 10pt，线宽 1pt - 横线/竖线渐变消失，虚线两侧带箭头 """, responses={ 200: { "description": "成功", "content": { "application/json": { "example": { "code": 0, "message": "success", "request_id": "mock-request-id", "data": { "annotated_image_url": SAMPLE_IMAGE_URL, "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}, }, }, } } }, }, 400: { "description": "参数错误 / 图片识别失败", "content": { "application/json": { "examples": { "图片参数错误": {"value": {"code": 1007, "message": "图片参数错误：必须且只能传 image_file / image_url / image_base64 其中一个", "request_id": "x", "data": None}}, "无法识别人像": {"value": {"code": 1001, "message": "无法识别人像", "request_id": "x", "data": None}}, "多张人脸": {"value": {"code": 1005, "message": "检测到多张人脸，仅支持单人照片", "request_id": "x", "data": None}}, } } }, }, }, ) async def face_measure( image_file: Optional[UploadFile] = File(default=None, description="上传图片文件（JPG/PNG，≤ 1 MB）"), image_url: Optional[str] = Form(default=None, description="图片 URL"), image_base64: Optional[str] = Form(default=None, description="图片 base64（需带 data:image/...;base64, 前缀）"), ): data = { "annotated_image_url": SAMPLE_IMAGE_URL, "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}, }, } return ok(data) # --------------------------------------------------------------------------- # 接口 2：C 端生发 # --------------------------------------------------------------------------- @app.post( "/api/v1/hair/grow", summary="接口2 C端生发", tags=["生发"], description=f""" 输入用户正面照，返回多个生发方案，每个方案包含： - 生发后效果图 URL - 对应的发际线形（如花瓣形、波浪形） - 合适度排序（order=1 最优） {_image_fields_desc} 图片同时支持 `multipart/form-data` 文件上传（字段名 `image_file`）。 --- **beauty_enabled**：是否对生发后图片开启美颜，默认 `false`。 """, responses={ 200: { "description": "成功", "content": { "application/json": { "example": { "code": 0, "message": "success", "request_id": "mock-request-id", "data": { "results": [ {"image_url": SAMPLE_IMAGE_URL, "hairline_type": "花瓣形", "order": 1}, {"image_url": SAMPLE_IMAGE_URL, "hairline_type": "波浪形", "order": 2}, ] }, } } }, }, 400: { "description": "参数错误 / 图片识别失败", "content": { "application/json": { "examples": { "图片参数错误": {"value": {"code": 1007, "message": "图片参数错误：必须且只能传 image_file / image_url / image_base64 其中一个", "request_id": "x", "data": None}}, "非正面照": {"value": {"code": 1003, "message": "角度问题，请上传正面照", "request_id": "x", "data": None}}, } } }, }, }, ) async def hair_grow( image_file: Optional[UploadFile] = File(default=None, description="上传图片文件（JPG/PNG，≤ 1 MB）"), image_url: Optional[str] = Form(default=None, description="图片 URL"), image_base64: Optional[str] = Form(default=None, description="图片 base64（需带 data:image/...;base64, 前缀）"), beauty_enabled: bool = Form(default=False, description="是否开启美颜效果，默认 false"), ): data = { "results": [ {"image_url": SAMPLE_IMAGE_URL, "hairline_type": "花瓣形", "order": 1}, {"image_url": SAMPLE_IMAGE_URL, "hairline_type": "波浪形", "order": 2}, ] } return ok(data) # --------------------------------------------------------------------------- # 接口 3：B 端生发 # --------------------------------------------------------------------------- @app.post( "/api/v1/hair/grow-b", summary="接口3 B端生发（医生/操作端）", tags=["生发"], description=""" 医生/操作端在用户原图上**手动划线标注**目标发际线后，上传划线图与原图，返回： - 最合适的发际线图片 URL - 生发后效果图 URL - 发际线形 **划线图片**：字段名前缀为 `marked_image_`，同样支持文件/URL/base64 三选一。 **原始用户照片**：字段名前缀为 `original_image_`，同样支持文件/URL/base64 三选一，**必填**。 > 两组图片的传参方式可以不同，例如划线图用 URL，原图用 base64，但各自组内严格互斥。 """, responses={ 200: { "description": "成功", "content": { "application/json": { "example": { "code": 0, "message": "success", "request_id": "mock-request-id", "data": { "best_hairline_image_url": SAMPLE_IMAGE_URL, "hair_growth_image_url": SAMPLE_IMAGE_URL, "hairline_type": "花瓣形", }, } } }, }, 400: { "description": "参数错误", "content": { "application/json": { "example": {"code": 1007, "message": "图片参数错误", "request_id": "x", "data": None} } }, }, }, ) async def hair_grow_b( marked_image_file: Optional[UploadFile] = File(default=None, description="划线图片文件（JPG/PNG，≤ 1 MB）"), marked_image_url: Optional[str] = Form(default=None, description="划线图片 URL"), marked_image_base64: Optional[str] = Form(default=None, description="划线图片 base64"), original_image_file: Optional[UploadFile] = File(default=None, description="原始用户照片文件（JPG/PNG，≤ 1 MB）"), original_image_url: Optional[str] = Form(default=None, description="原始用户照片 URL"), original_image_base64: Optional[str] = Form(default=None, description="原始用户照片 base64"), ): data = { "best_hairline_image_url": SAMPLE_IMAGE_URL, "hair_growth_image_url": SAMPLE_IMAGE_URL, "hairline_type": "花瓣形", } return ok(data) # --------------------------------------------------------------------------- # 接口 4：用户特征 # --------------------------------------------------------------------------- @app.post( "/api/v1/face/features", summary="接口4 用户特征分析", tags=["人脸分析"], description=f""" 输入用户照片，返回 N 个用户面部特征字段。 {_image_fields_desc} 图片同时支持 `multipart/form-data` 文件上传（字段名 `image_file`）。 --- **返回格式**：`data.features` 为一个 **JSON 字符串**（不是对象），需要在客户端 `JSON.parse()` 后使用。 当前优先返回字段： | 字段 | 类型 | 说明 | |------|------|------| | face_shape | string | 脸形，如"鹅蛋脸" | | eyebrow_shape | string | 眉形，如"柳叶眉" | | facial_age | int | 面部年龄 | | dynamic_static_type | string | 动静类型，如"静态" | | gender | string | 性别，如"女" | | gene_style | object | 面部特征对应的基因风格 | > 字段后续可随时增删，不固定，客户端按需取用即可。 """, responses={ 200: { "description": "成功", "content": { "application/json": { "example": { "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": "基因风格示例"}}', }, } } }, }, 400: { "description": "参数错误 / 图片识别失败", "content": { "application/json": { "example": {"code": 1001, "message": "无法识别人像", "request_id": "x", "data": None} } }, }, }, ) async def face_features( image_file: Optional[UploadFile] = File(default=None, description="上传图片文件（JPG/PNG，≤ 1 MB）"), image_url: Optional[str] = Form(default=None, description="图片 URL"), image_base64: Optional[str] = Form(default=None, description="图片 base64（需带 data:image/...;base64, 前缀）"), ): features = json.dumps( { "face_shape": "鹅蛋脸", "eyebrow_shape": "柳叶眉", "facial_age": 26, "dynamic_static_type": "静态", "gender": "女", "gene_style": {"label": "面部特征标签", "style": "基因风格示例"}, }, ensure_ascii=False, ) return ok({"features": features}) # --------------------------------------------------------------------------- # 接口 5：发际线 PNG 生成 # --------------------------------------------------------------------------- @app.post( "/api/v1/hairline/generate", summary="接口5 发际线PNG生成", tags=["人脸分析"], description=f""" 输入用户照片，返回 N 张用户发际线的 PNG 图片，并标注最合适发际线的面部中间点坐标。 {_image_fields_desc} 图片同时支持 `multipart/form-data` 文件上传（字段名 `image_file`）。 --- **返回说明**： - `hairline_images`：发际线 PNG 列表，数量 N 不固定，已按合适度**从高到低排序**（`order=1` 最合适） - `best_hairline_center_point`：最合适发际线的面部中间点坐标，以**原图像素**为基准（左上角为原点，x 向右，y 向下） """, responses={ 200: { "description": "成功", "content": { "application/json": { "example": { "code": 0, "message": "success", "request_id": "mock-request-id", "data": { "hairline_images": [ {"image_url": SAMPLE_IMAGE_URL, "order": 1}, {"image_url": SAMPLE_IMAGE_URL, "order": 2}, ], "best_hairline_center_point": {"x": 540, "y": 430}, }, } } }, }, 400: { "description": "参数错误 / 图片识别失败", "content": { "application/json": { "example": {"code": 1002, "message": "人像分辨率过低", "request_id": "x", "data": None} } }, }, }, ) async def hairline_generate( image_file: Optional[UploadFile] = File(default=None, description="上传图片文件（JPG/PNG，≤ 1 MB）"), image_url: Optional[str] = Form(default=None, description="图片 URL"), image_base64: Optional[str] = Form(default=None, description="图片 base64（需带 data:image/...;base64, 前缀）"), ): data = { "hairline_images": [ {"image_url": SAMPLE_IMAGE_URL, "order": 1}, {"image_url": SAMPLE_IMAGE_URL, "order": 2}, ], "best_hairline_center_point": {"x": 540, "y": 430}, } return ok(data) # --------------------------------------------------------------------------- # 健康检查 # --------------------------------------------------------------------------- @app.get("/health", include_in_schema=False) async def health(): return {"status": "ok"} @app.get("/", include_in_schema=False) async def index(): return {"service": "旷视五接口", "version": "0.1.0", "docs": f"{BASE_URL}/docs"}