AI识别手部异常

手部异常识别 HTTP 服务 - API 文档

一、概述

本服务提供基于 HTTP 的手部图像检测接口，可识别手部是否存在以下情况：手部完整、美甲、手部伤口、佩戴戒指、长指甲、灰指甲。

项目	说明
默认地址	http://<服务端IP>:5000
协议	HTTP/1.1
数据格式	请求/响应均为 JSON（除上传文件为 multipart）；图片可传文件或 Base64
编码	建议 UTF-8

---

二、通用约定

2.1 统一响应结构

除健康检查外，业务接口均采用以下 JSON 结构：

成功时：

{
  "success": true,
  "message": "检测成功",
  "data": { ... }
}

字段	类型	说明
success	boolean	是否成功
message	string	提示信息
data	object / null	业务数据，失败时为 null

失败时（如 400）：

{
  "success": false,
  "message": "错误描述",
  "data": null
}

2.2 HTTP 状态码

状态码	说明
200	成功
400	请求参数错误（如未上传图片、图片无法解码）
500	服务端检测异常

---

三、接口列表

3.1 健康检查

用于探测服务是否存活，不涉及图片与业务逻辑。

请求

项目	说明
方法	GET
路径	/health
请求体	无

响应

状态码	说明
200	服务正常

响应体示例

{
  "status": "ok"
}

调用示例

curl -X GET http://127.0.0.1:5000/health

---

3.2 仅返回识别结果（不返回图片）

上传一张图片，返回手部检测结果（JSON），不包含标注图。适合只需结构化结果的场景。

请求

项目	说明
方法	POST
路径	/detect
Content-Type	见下方两种方式二选一

方式一：表单上传图片文件

• Content-Type: multipart/form-data
• 表单字段名必须为 image，值为图片文件（如 .jpg、.png）

方式二：JSON 传 Base64 图片

• Content-Type: application/json
• 请求体为 JSON，且包含以下字段之一：
  • image_base64：图片的 Base64 编码字符串
  • imageBase64：同上（兼容驼峰命名）
• Base64 可带 data:image/jpeg;base64, 等前缀，服务会自动截取逗号后的内容解码

响应（成功 200）

data 结构：

字段	类型	说明
summary	string[]	简短结果摘要，如 ["美甲: 85.0% [稳定]", "手部完整: 90.0% [稳定]"]
detections	object[]	检测项列表，每项见下表
hand_count	number	检测到的手的数量（0 或 1 等）

detections 每项字段：

字段	类型	说明
type	string	类型标识，见「识别类型枚举」
class_name	string	中文名称
confidence	number	置信度 0~1
box	number[] | null	可选，边界框 [x1, y1, x2, y2]，像素坐标

响应体示例（成功）

{
  "success": true,
  "message": "检测成功",
  "data": {
    "summary": [
      "美甲: 85.0% [稳定]",
      "手部完整: 90.0% [稳定]"
    ],
    "detections": [
      {
        "type": "nail_art",
        "class_name": "美甲",
        "confidence": 0.85,
        "box": [120, 200, 180, 260]
      },
      {
        "type": "normal",
        "class_name": "手部完整",
        "confidence": 0.9,
        "box": [80, 100, 400, 480]
      }
    ],
    "hand_count": 1
  }
}

响应体示例（失败 400）

{
  "success": false,
  "message": "请上传图片 (字段名 image)",
  "data": null
}

调用示例

# 表单上传文件
curl -X POST http://127.0.0.1:5000/detect -F "image=@/path/to/photo.jpg"

# JSON Base64（将 YOUR_BASE64_STRING 替换为实际 Base64）
curl -X POST http://127.0.0.1:5000/detect \
  -H "Content-Type: application/json" \
  -d '{"image_base64":"YOUR_BASE64_STRING"}'

---

3.3 返回识别结果 + 标注图（Base64）

上传一张图片，返回识别结果的同时，返回一张在图上画好检测框与文字的标注图（JPEG），以 Base64 形式放在 data.image_base64。适合需要"原图+结果图"的场景。

请求

与 3.2 仅返回识别结果 完全一致，仅路径不同。

项目	说明
方法	POST
路径	/detect_image
Content-Type	multipart/form-data（字段 image）或 application/json（字段 image_base64 / imageBase64）

响应（成功 200）

data 在 3.2 的基础上多一个字段：

字段	类型	说明
summary	string[]	同 3.2
detections	object[]	同 3.2
hand_count	number	同 3.2
image_base64	string	标注后的图片（JPEG）的 Base64 编码，可直接用于展示或保存为 .jpg

响应体示例（成功，仅摘录 data）

{
  "success": true,
  "message": "检测成功",
  "data": {
    "summary": ["美甲: 85.0% [稳定]"],
    "detections": [
      {
        "type": "nail_art",
        "class_name": "美甲",
        "confidence": 0.85,
        "box": [120, 200, 180, 260]
      }
    ],
    "hand_count": 1,
    "image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBD..."
  }
}

前端使用示例（将返回的 base64 显示为图片）：

<img src="data:image/jpeg;base64,{{ data.image_base64 }}" />

调用示例

curl -X POST http://127.0.0.1:5000/detect_image -F "image=@/path/to/photo.jpg"

---

四、识别类型枚举

检测结果中的 type 与 class_name 对应关系如下：

type	class_name
normal	手部完整
nail_art	美甲
wound	手部伤口
ring	佩戴戒指
long_nail	长指甲
fungal_nail	灰指甲

同一张图中可能同时返回多项（如既有 normal 也有 nail_art），以实际检测为准。

---

五、常见错误 message

message	原因	处理建议
请上传图片 (字段名 image)	使用 multipart 时未带 image 或文件为空	检查表单字段名为 image 且选择了文件
请提供 image_base64	使用 JSON 时未传 base64 字段	使用 image_base64 或 imageBase64
无法解码图片 / Base64 图片解码失败	图片损坏或非图片格式	确认为合法 jpg/png 等
Base64 解码失败	Base64 字符串非法	检查编码是否正确、无换行/空格截断
请使用 multipart/form-data (image 文件) 或 application/json (image_base64)	Content-Type 既不是表单也不是 JSON	按文档使用两种方式之一
检测异常: xxx	服务端推理出错	查看服务端日志，确认图片尺寸/格式合理

---

六、附录：接口速览

方法	路径	说明
GET	/health	健康检查
POST	/detect	上传图片，仅返回识别结果（JSON）
POST	/detect_image	上传图片，返回识别结果 + 标注图 Base64

所有 POST 接口的图片输入方式：表单字段 image 或 JSON 字段 image_base64 / imageBase64。