人体姿态估计接口

本文档描述了人体姿态估计（Human Pose Estimation, HPE）服务的 HTTP API 接口规范。

目录

• 人体姿态估计接口
  • 目录
  • 服务概述
  • 接口说明
    • 请求
      • 请求头
    • 响应
      • 成功响应
      • 响应体示例
    • 错误码
      • 错误响应示例
  • 响应数据结构
  • 关键点定义
    • 骨骼连接定义
    • 可视化示例
  • 使用示例
    • Python 示例
    • Bash/cURL 示例
    • cURL 快速示例
  • 注意事项

---

服务概述

HPE 服务提供基于深度学习的人体姿态估计能力，可从输入图像中检测人体并识别 133 个关键点（全身姿态，包含身体、手部及面部关键点）。

• 服务端点：https://api.pose.weihua-iot.cn/hpe

---

接口说明

请求

属性	说明
URL	/hpe
方法	POST
Content-Type	image/jpeg 或 image/png
请求体	原始图像二进制数据
最大请求体大小	10 MB
超时时间	30 秒

请求头

名称	必填	说明
Content-Type	是	必须为 image/jpeg 或 image/png
Content-Length	否	请求体字节数（推荐提供）

响应

成功响应

HTTP 状态码	Content-Type	说明
200	application/json	检测到姿态，返回 JSON 数据
200	无内容	未检测到人体姿态，返回空响应体

响应体示例

{
  "frame_index": 0,
  "reference_size": [1920, 1080],
  "bbox": [[100, 150, 400, 800], [500, 200, 750, 850]],
  "bbox_confidence": [0.95, 0.87],
  "keypoints": [
    [[x1, y1], [x2, y2], ...],
    [[x1, y1], [x2, y2], ...]
  ],
  "keypoints_confidence": [
    [0.9, 0.85, ...],
    [0.88, 0.92, ...]
  ]
}

错误码

HTTP 状态码	错误类型	说明
400	Bad Request	请求体为空或图像解码失败
408	Request Timeout	推理超时（超过 30 秒）
413	Payload Too Large	请求体超过 10 MB 限制
415	Unsupported Media Type	Content-Type 不是 image/jpeg 或 image/png
503	Service Unavailable	服务过载，请求队列已满（最大 16 个请求）

错误响应示例

{
  "error": "Unsupported Media Type",
  "detail": "Expected Content-Type: image/jpeg or image/png, got: text/plain"
}

---

响应数据结构

字段	类型	说明
frame_index	int	帧索引，HTTP 接口始终返回 0
reference_size	[int, int]	输入图像尺寸，格式为 [宽度, 高度]
bbox	[[x1, y1, x2, y2], ...]	检测到的人体边界框列表，每个边界框包含左上角 (x1, y1) 和右下角 (x2, y2) 坐标
bbox_confidence	[float, ...] 或 null	每个边界框的置信度分数（0-1），可能为空
keypoints	[[[x, y], ...], ...]	每个检测到的人体的 133 个关键点坐标列表
keypoints_confidence	[[float, ...], ...] 或 null	每个关键点的置信度分数（0-1），可能为空

---

关键点定义

本服务使用 COCO WholeBody 格式，共包含 133 个关键点：

索引范围	数量	描述
0-16	17	身体关键点（鼻子、眼睛、耳朵、肩膀、肘部、手腕、髋部、膝盖、脚踝等）
17-22	6	脚部关键点
23-90	68	面部关键点
91-111	21	左手关键点
112-132	21	右手关键点

骨骼连接定义

关键点之间通过骨骼（Bone）连接形成人体骨架结构。主要骨骼连接如下：

部位	连接关系（0-based 索引）
腿部	(15, 13), (13, 11), (16, 14), (14, 12), (11, 12)
躯干	(5, 11), (6, 12), (5, 6)
手臂	(5, 7), (7, 9), (6, 8), (8, 10)
头部	(1, 2), (0, 1), (0, 2), (1, 3), (2, 4)
左脚	(15, 17), (15, 18), (15, 19)
右脚	(16, 20), (16, 21), (16, 22)
左手	手腕(91)连接至各指根，每指4个关节依次连接
右手	手腕(112)连接至各指根，每指4个关节依次连接

可视化示例

项目提供了完整的可视化脚本 scripts/vis_whole_body.py，包含：

• 关键点定义：body_landmarks、foot_landmarks、face_landmarks、hand_landmarks 字典，包含每个关键点的索引、名称和颜色
• 骨骼定义：body_bones、hand_bones 列表，定义了关键点之间的连接关系
• 可视化函数：
  • visualize_whole_body() - 可视化单人 133 个关键点
  • visualize_17_keypoints() - 仅可视化 17 个身体关键点

---

使用示例

完整的客户端示例代码位于 scripts 目录下。

Python 示例

参见 scripts/client_example.py。

该脚本使用 PEP 723 内联脚本元数据，可通过 uv 直接运行，无需手动安装依赖：

# 使用 uv 直接运行（自动安装依赖）
uv run scripts/client_example.py figures/sample.jpg

# 指定自定义 URL
uv run scripts/client_example.py figures/sample.jpg --url https://api.pose.weihua-iot.cn/hpe

# 或使用传统方式（需先安装 httpx）
pip install httpx
python scripts/client_example.py figures/sample.jpg

Bash/cURL 示例

参见 scripts/client_example.sh。

# 赋予执行权限
chmod +x scripts/client_example.sh

# 发送图像
./scripts/client_example.sh figures/sample.jpg

# 指定自定义 URL
./scripts/client_example.sh figures/sample.jpg https://api.pose.weihua-iot.cn/hpe

cURL 快速示例

# 发送 JPEG 图像
curl -X POST \
  -H "Content-Type: image/jpeg" \
  --data-binary @figures/sample.jpg \
  https://api.pose.weihua-iot.cn/hpe

# 发送 PNG 图像并使用 jq 格式化输出
curl -s -X POST \
  -H "Content-Type: image/png" \
  --data-binary @figures/sample.png \
  https://api.pose.weihua-iot.cn/hpe | jq .

# 将结果保存到文件
curl -X POST \
  -H "Content-Type: image/jpeg" \
  --data-binary @figures/sample.jpg \
  -o result.json \
  https://api.pose.weihua-iot.cn/hpe

---

注意事项

1. 图像格式：仅支持 JPEG 和 PNG 格式，其他格式将返回 415 错误。
2. 图像大小：请确保图像文件不超过 10 MB，否则将返回 413 错误。
3. 并发限制：服务最多同时处理 16 个请求，超出后将返回 503 错误。
4. 超时处理：单次推理最长等待 30 秒，超时将返回 408 错误。
5. 空结果处理：当未检测到人体时，服务返回 HTTP 200 但响应体为空，请在客户端代码中正确处理此情况。