# SegmentPerson API

人像抠图 / 主体抠图。请求体为 **`multipart/form-data`**。

**基址**：`https://segment-person.model.wgdl.tech`

| 用途 | 方法 | 路径 |
|------|------|------|
| 健康检查 | GET | `/health` |
| 人像抠图 | POST | `/api/segment` |
| 主体抠图 | POST | `/api/segment_subject` |
| 主体抠图（兼容） | POST | `/api/segment_commodity` |
| 前置检测元数据 | POST | `/api/preprocess` |
| OpenAPI | GET | `/docs` |

线上交互文档也可直接打开：`https://segment-person.model.wgdl.tech/docs`

---

## GET `/health`

### 响应要点

| 字段 | 说明 |
|------|------|
| `status` | `"ok"` |
| `loaded_models` | 已加载模型列表 |
| `device.using_gpu` | 是否在 GPU 上推理 |
| `limits` | 入图像素约束（以线上为准） |

当前部署常见 `limits`：

| 项 | 值 |
|----|-----|
| `min_side` | 32 |
| `max_side` | **3072** |
| `max_pixels` | 见 `/health`（约 9.4M） |

超限返回 HTTP **400**。

---

## 输入图（三选一）

适用于 `/api/segment`、`/api/segment_subject`、`/api/preprocess`。

| 字段 | 说明 |
|------|------|
| `s3_path` | OSS 路径 `bucket/key/...`（服务端直读，推荐） |
| `image_url` | `http(s)` 图片 URL |
| `file` | 上传文件 |

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

---

## POST `/api/segment`（人像）

前置流程由 `preprocess` 控制：

- `true`：YOLO 检人 → 中心种子扩散 → `union_bbox` 裁切 → 抠图 + refine
- `false`（默认）：整图直抠 + refine

### 主要参数

| 字段 | 默认 | 说明 |
|------|------|------|
| `method` | `person-u2netp` | 模型 ID，见下方列表 |
| `preprocess` | `false` | 是否走 YOLO 前置 |
| `crop_expand_mode` | `expand` | `expand`=四向最大化；`cap_bottom`=向下仅留全图高约 3% 余量 |
| `yolo_crop` | `false` | 旧版单人裁切；与 `preprocess` 二选一，后者优先 |
| `threshold` | `96` | mask 二值化阈值 |
| `min_component_ratio` | `0.04` | refine 最小连通域比例 |
| `inner_solidify_distance_px` | `4` | refine 内部实心化距离 |
| `warmup` | `false` | 推理前预热 |
| `output` | `auto` | `auto` / `url` / `b64` |
| `user_id` | — | OSS 结果路径 scope（可选） |

### `output` 说明

| 值 | 行为 |
|----|------|
| `auto` | 已配置 OSS 则返回 `image_url`，否则返回 `refined_png_b64` |
| `url` | 必须能上传 OSS，结果在 `image_url` |
| `b64` | 结果 PNG 在 `refined_png_b64` |

### 响应要点

| 字段 | 说明 |
|------|------|
| `image_url` | 结果 PNG 的 URL（`output` 为 url/auto 且 OSS 可用时） |
| `refined_png_b64` | 结果 PNG 的 base64（`output=b64` 或无 OSS 时） |
| `method` | 实际使用的模型 |
| `image_width` / `image_height` | 结果图尺寸 |
| `source_width` / `source_height` | 原图尺寸 |
| `preprocess_enabled` | 是否开启了前置 |
| `preprocess` | 开启时的检测/裁切元数据 |
| `fetch_ms` / `decode_ms` / `input_ms` | 拉图与解码 |
| `load_ms` / `model_ms` / `refine_ms` / `total_ms` / `wall_ms` | 模型与推理 |
| `upload_ms` / `response_ms` | 结果上传与响应组装 |

---

## POST `/api/segment_subject`（主体）

跳过 YOLO preprocess 与 mask refine，适合商品 / 通用主体。

旧路径 `/api/segment_commodity` **行为相同**，建议新接入用 `segment_subject`。

### 主要参数

| 字段 | 默认 | 说明 |
|------|------|------|
| `method` | `person-bria-rmbg` | 推荐见下表 |
| `threshold` | `96` | 二值化阈值（主体路径精简后处理） |
| `min_component_ratio` | `0.04` | 同左 |
| `inner_solidify_distance_px` | `4` | 同左 |
| `warmup` | `false` | 预热 |
| `output` | `auto` | 同人像 |
| `user_id` | — | 可选 |

---

## POST `/api/preprocess`

只做人检测与裁切元数据，**不返回抠图结果**。入参：`image_url` / `s3_path` / `file`、`crop_expand_mode`、`output`、`user_id`。

---

## method 列表

| id | 说明 | 人像 | 主体推荐 |
|----|------|------|----------|
| `person-u2net` | U²-Net 全量 | ✓ | ✓ |
| `person-u2netp` | 轻量（人像默认） | ✓ | ✓ |
| `person-silueta` | 体积小 | ✓ | ✓ |
| `person-isnet` | 边缘更细 | ✓ | ✓ |
| `person-birefnet-portrait` | 人像专精 | ✓ | 非人主体不优先 |
| `person-birefnet-general` | 通用高精度 | ✓ | ✓ 推荐 |
| `person-birefnet-general-lite` | 质量/速度折中 | ✓ | ✓ 推荐 |
| `person-bria-rmbg` | BRIA 抠背景（主体默认 / 常预热） | ✓ | ✓ 推荐 |

> 当前线上实例默认预热 `person-bria-rmbg`；其它 method 首次调用会加载模型，耗时更长。

---

## 调用示例

### 人像（URL + 默认直抠）

```bash
BASE='https://segment-person.model.wgdl.tech'

curl -sS -X POST "${BASE}/api/segment" \
  -F 'image_url=https://example.com/person.jpg' \
  -F 'method=person-bria-rmbg' \
  -F 'preprocess=false' \
  -F 'output=b64'
```

### 人像（开启 YOLO 前置）

```bash
curl -sS -X POST "${BASE}/api/segment" \
  -F 'file=@./person.jpg' \
  -F 'method=person-bria-rmbg' \
  -F 'preprocess=true' \
  -F 'crop_expand_mode=expand' \
  -F 'output=b64'
```

### 主体抠图

```bash
curl -sS -X POST "${BASE}/api/segment_subject" \
  -F 'file=@./product.jpg' \
  -F 'method=person-bria-rmbg' \
  -F 'output=b64'
```

### Python

```python
import base64
import requests

BASE = "https://segment-person.model.wgdl.tech"

with open("person.jpg", "rb") as f:
    r = requests.post(
        f"{BASE}/api/segment",
        files={"file": ("person.jpg", f, "image/jpeg")},
        data={
            "method": "person-bria-rmbg",
            "preprocess": "false",
            "output": "b64",
        },
        timeout=120,
    )
r.raise_for_status()
data = r.json()
png = base64.b64decode(data["refined_png_b64"])
open("out.png", "wb").write(png)
```

---

## 错误

| 情况 | 表现 |
|------|------|
| 参数校验失败 | HTTP **422** |
| 尺寸 / 业务约束 | HTTP **400** |
| 推理超时 | HTTP **504** |