Face State

Detect facial attributes such as agender, age, emotion and race.

原始信息汇总

数据集概述：Face State API

Face State（人脸状态） 是一个用于从照片中检测人脸属性的 API，能够识别人脸的年龄、性别、种族、年龄段和情绪。用户可以通过图片 URL、Base64 编码文件或直接上传图片来获取分析结果，并获得每个属性对应的置信度评分。

---

核心功能

• 人脸属性检测：支持检测 age（年龄）、gender（性别）、race（种族）、age_group（年龄段）、emotion（情绪）五种属性。
• 多脸支持：可同时分析图片中的多张人脸，按置信度排序，返回最多 20 张人脸结果。
• 输入方式灵活：支持 Base64 编码图片、公开图片 URL、原始二进制数据（JPEG/PNG）、multipart 表单上传及 URL 编码表单。

---

API 端点

方法	路径	描述
POST	/analyze	发送图片并返回检测到的人脸及其属性
GET	/health	服务健康检查（存活/就绪）
GET	/v1/models	获取当前模型版本及就绪状态

---

请求参数（POST /analyze）

字段	类型	描述
image	string	Base64 编码的 JPEG/PNG/WebP 图片（可选 data:image/... URI）
image_url	string	图片的公开 HTTP(S) URL（服务端抓取）
attributes	array	需要检测的属性子集，默认为全部
min_face_confidence	number	人脸检测置信度阈值，默认 0.5
max_faces	integer	返回的最大人脸数，默认 5，上限 20

注意：image 和 image_url 只能二选一，不能同时提供。

---

响应字段说明

顶层响应字段：

字段	描述
request_id	请求唯一标识
model_version	使用的模型堆栈版本
processing_time_ms	服务端处理时间（毫秒）
attributes	已计算的属性集合
faces	检测到的人脸列表（无检测到时为空数组）

每张人脸包含的字段：

字段	描述
bbox	人脸边界框坐标 {x1, y1, x2, y2}（像素）
face_confidence	人脸检测置信度
age	预测年龄（整数）
age_group	年龄段（0-2, 3-9, 10-19, 20-29, 30-39, 40-49, 50-59, 60-69, 70+）
gender	性别（Female / Male）
race	种族（White, Black, Latino Hispanic, East Asian, Southeast Asian, Indian, Middle Eastern）
emotion	情绪（Anger, Contempt, Disgust, Fear, Happiness, Neutral, Sadness, Surprise）
*_scores	各属性标签对应的置信度分数

---

错误处理

状态码	含义
400	缺少图片或参数组合无效（如同时提供 image 和 image_url）
401	缺少或无效的代理密钥
413	请求体超过 8 MB 上传限制
422	图片无法处理、Base64 无效、不支持的数据 URI、未知属性或参数无效
429	超出速率限制
500	内部分析失败

错误响应格式为 JSON：{"detail": "<message>"}

---

使用限制

项目	限制
最大上传大小	8 MB / 请求
最大图片尺寸	4096 px（长边，更大图片会被缩小）
最大人脸数	默认 5，可通过 max_faces 调至 20
速率限制	根据 RapidAPI 订阅层级配置

---

注意事项

• image_url 抓取仅支持公开的 HTTP(S) URL。
• 无可检测人脸时，faces 返回空数组。
• emotion 描述的是面部表情，而非人物身份。
• model_version 会在模型堆栈变更时更新，如需结果可复现，建议在集成时固定该版本。
• race 为基于视觉外观的推断结果，应视为软信号而非客观标签。