M2FP文档详解：API接口参数说明与返回格式解析

📖 项目简介：M2FP 多人人体解析服务

在计算机视觉领域，人体解析（Human Parsing）是一项关键的细粒度语义分割任务，旨在将图像中的人体分解为多个语义明确的身体部位，如头发、面部、上衣、裤子、手臂等。相较于传统的人体分割仅区分“人”与“背景”，人体解析提供了更精细的像素级理解能力，广泛应用于虚拟试衣、动作识别、智能安防和AR/VR场景。

M2FP（Mask2Former-Parsing）是基于 ModelScope 平台发布的先进多人人体解析模型，专为复杂真实场景设计。该模型融合了Mask2Former 架构优势与针对人体结构优化的训练策略，能够在单张图像中同时处理多个人物，并输出高精度的身体部位分割掩码（Mask）。本部署版本进一步集成了Flask WebUI和可视化拼图算法，支持无GPU环境下的稳定运行，极大降低了技术落地门槛。

💡 核心亮点速览： - ✅精准多人解析：支持图像中多个个体的同时检测与部位分割 - ✅内置可视化合成：自动将离散 Mask 拼接为彩色语义图，无需额外后处理 - ✅CPU友好推理：经深度优化，可在纯CPU环境下实现秒级响应 - ✅环境零报错：锁定 PyTorch 1.13.1 + MMCV-Full 1.7.1 黄金组合，彻底解决兼容性问题

🛠️ API 接口设计与调用方式

本服务提供标准 HTTP RESTful API 接口，便于集成至各类业务系统或自动化流程中。所有请求通过POST /api/predict端点提交，支持表单上传（form-data）和 JSON 数据两种方式。

🔗 基础信息

请求方法：POST
接口地址：http://<your-host>:<port>/api/predict
Content-Type 支持：
multipart/form-data（推荐用于图片上传）
application/json（适用于 Base64 编码图像）

🧩 请求参数说明

以下是各请求字段的详细定义：

| 参数名 | 类型 | 必填 | 描述 | |-------|------|------|------| |image| File 或 String(Base64) | 是 | 输入图像文件（JPEG/PNG格式），最大支持 4096x4096 分辨率 | |output_type| String | 否 | 返回结果类型：
mask_list：仅返回原始掩码列表
colored_map：返回合成后的彩色分割图（默认）
both：两者都返回 | |confidence_threshold| Float | 否 | 置信度阈值（0.0~1.0），低于此值的区域不参与输出，默认0.5| |return_visualization| Boolean | 否 | 是否返回可视化拼图结果，默认true|

示例 1：使用 form-data 上传图片（推荐）

curl -X POST http://localhost:5000/api/predict \ -F "image=@./test.jpg" \ -F "output_type=both" \ -F "confidence_threshold=0.6" \ -H "Accept: application/json"

示例 2：使用 Base64 图像数据发送 JSON 请求

import base64 import requests with open("test.jpg", "rb") as f: img_base64 = base64.b64encode(f.read()).decode('utf-8') payload = { "image": img_base64, "output_type": "both", "confidence_threshold": 0.6, "return_visualization": True } response = requests.post("http://localhost:5000/api/predict", json=payload) print(response.json())

📤 返回格式详解

API 的响应遵循统一的 JSON 结构，包含状态码、消息提示以及核心结果数据。根据output_type设置不同，返回内容会有所变化。

✅ 成功响应结构（HTTP 200）

{ "code": 200, "msg": "success", "data": { "width": 1920, "height": 1080, "num_persons": 3, "masks": [...], "colored_map": "base64_encoded_png" } }

`data`字段详细说明：

| 字段 | 类型 | 条件返回 | 说明 | |------|------|----------|------| |width,height| Integer | 总是返回 | 原始输入图像的宽高（像素） | |num_persons| Integer | 总是返回 | 检测到的人物数量（基于连通域分析） | |masks| Array