# HumanParser API

人体语义解析：输入一张人像，输出与原图同尺寸的 **逐像素类别 mask**（18 类）。

**基址**：`https://human-parser.model.wgdl.tech`

| 用途 | 方法 | 路径 |
|------|------|------|
| 健康检查 | GET | `/health` |
| 解析 | POST | `/human_parser/predict` |
| OpenAPI | GET | `/docs` |

---

## GET `/health`

### 响应示例（节选）

```json
{
  "status": "ok",
  "model_loaded": true,
  "device": "cuda:0",
  "gpu": {
    "host_gpu_index": 3,
    "gpu_name": "NVIDIA L20"
  },
  "id2label": {
    "0": "background",
    "1": "face",
    "2": "hair"
  },
  "limits": {
    "min_side": 32,
    "max_side": 2048,
    "max_pixels": 4194304,
    "fetch_max_bytes": 52428800
  }
}
```

以线上 `limits` 为准；超限请求会被拒绝。

---

## POST `/human_parser/predict`

### 请求

- **Header**：`Content-Type: application/json`
- **Body**：以下图像来源 **至少提供一种**

| 字段 | 类型 | 说明 |
|------|------|------|
| `image` | string | Data URL（`data:image/...;base64,...`）/ 纯 base64 / 或以 `http(s)://` 开头的图片 URL |
| `image_url` | string | `http://` 或 `https://` 图片地址 |
| `s3_path` | string | OSS 路径，如 `bucket/path/to.jpg`（需服务端已配置 OSS 凭证） |

**优先级**：`s3_path` > `image` > `image_url`

### 约束

| 项 | 当前默认 |
|----|----------|
| 最短边 | ≥ 32 px |
| 最长边 | ≤ **2048**（2K） |
| 像素数 | ≤ `max_pixels`（见 `/health`） |
| 输入字节 | ≤ 50MB（URL / base64 / OSS） |

超限返回 **HTTP 400**，例如：

```json
{"detail": "图像边长过大（当前 3000×2000），最长边须 ≤ 2048"}
```

### 成功响应（HTTP 200）

| 字段 | 说明 |
|------|------|
| `success` | `true` |
| `pred_shape` | `[H, W]`，与输入图一致 |
| `pred_uint8_b64` | 逐像素类别 id（0–17）的 `uint8` 扁平数组，再 base64 |
| `id2label` | 类别映射 |
| `elapsed_ms` | 总耗时（ms） |
| `timing_ms` | 分阶段耗时 |

### 类别（`id2label`）

| id | 名称 |
|----|------|
| 0 | background |
| 1 | face |
| 2 | hair |
| 3 | top |
| 4 | dress |
| 5 | skirt |
| 6 | pants |
| 7 | belt |
| 8 | bag |
| 9 | hat |
| 10 | scarf |
| 11 | glasses |
| 12 | arms |
| 13 | hands |
| 14 | legs |
| 15 | feet |
| 16 | torso |
| 17 | jewelry |

### 调用示例

```bash
BASE='https://human-parser.model.wgdl.tech'

# URL 入图
curl -sS -X POST "${BASE}/human_parser/predict" \
  -H 'Content-Type: application/json' \
  -d '{"image_url":"https://example.com/photo.jpg"}'

# base64 入图
curl -sS -X POST "${BASE}/human_parser/predict" \
  -H 'Content-Type: application/json' \
  -d '{"image":"data:image/jpeg;base64,/9j/4AAQ..."}'
```

```python
import base64
import requests

BASE = "https://human-parser.model.wgdl.tech"

with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

r = requests.post(
    f"{BASE}/human_parser/predict",
    json={"image": f"data:image/jpeg;base64,{b64}"},
    timeout=120,
)
r.raise_for_status()
data = r.json()
assert data["success"]
# data["pred_uint8_b64"] -> decode -> reshape(data["pred_shape"])
```

### 解析 mask（Python）

```python
import base64
import numpy as np

raw = base64.b64decode(data["pred_uint8_b64"])
h, w = data["pred_shape"]
mask = np.frombuffer(raw, dtype=np.uint8).reshape(h, w)
# mask[y, x] 为类别 id
```

### 失败

| 情况 | 表现 |
|------|------|
| 参数 / 尺寸不合法 | HTTP **400**，`{"detail":"..."}` |
| 推理异常 | 可能 HTTP 200 且 `success: false`，带 `error` |