Face Analysis API — Age, Gender, Expression & Landmarks

Detect all faces in an image and get per-face attributes: age, gender, expression, beauty score, 72 landmark points, and head pose angles.

原始信息汇总

Face Analysis API — Age, Gender, Expression & Landmarks 数据集概述

基本信息

• API名称：Face Analysis API — Age, Gender, Expression & Landmarks
• 提供商：APISphere
• 类别：Video, Images
• 版本：v1 (current)
• 订阅计划：
  • BASIC: $0.00 / mo
  • PRO: $8.91 / mo
  • ULTRA: $35.91 / mo
  • MEGA: $89.91 / mo

API概述

检测图像中的所有面部，并获取每个面部的属性：年龄、性别、表情、美丽分数、72个关键点以及头部姿态角度。

目标用户

✅ 适用场景

• 通过活动或零售图像测量受众人口统计的分析平台。
• 需要精确面部关键点位置和头部姿态的AR/VR开发者。
• 根据面部属性自动标记图像的相册管理应用。
• 构建虚拟试妆功能的美容和化妆品平台。
• 研究图像数据集中面部表情或人口统计学的研究人员。

❌ 不适用场景

• 识别特定个体（此API检测属性，而非身份）。
• 实时视频流处理（单图像端点）。
• 需要政府签发身份证件的法定年龄验证。
• 需要临床级准确性的情绪检测。

端点

• 端点：POST /v1/face/analyze
• 功能：上传JPEG、PNG、BMP、WEBP或GIF图像，接收检测到的面部及其年龄、性别、表情、美丽分数、关键点和头部姿态。

支持的文件格式与限制

• 支持格式：JPEG, PNG, BMP, WEBP, GIF
• 文件大小限制：不超过10 MB

返回数据字段

字段	类型	描述
faces[].x	int	边界框的左边缘
faces[].y	int	边界框的顶部边缘
faces[].width	int	边界框的宽度
faces[].height	int	边界框的高度
faces[].age	int	估计年龄（岁）
faces[].gender	string	检测到的性别
faces[].expression	string	检测到的面部表情
faces[].beauty_score	float	美丽分数
faces[].landmarks	array	72个面部关键点，每个点包含 x 和 y
faces[].pose.pitch	float	头部上下倾斜角度（度）
faces[].pose.roll	float	头部左右倾斜角度（度）
faces[].pose.yaw	float	头部左右转动角度（度）

主要特点

• 一次调用获取全面部属性：年龄、性别、表情、美丽分数、关键点和头部姿态。
• 72个面部关键点：为AR叠加、面部对齐和变形提供精确的几何数据。
• 头部姿态估计：提供俯仰角、翻滚角和偏航角以确定3D面部方向。
• 多面部处理：可处理集体照和拥挤场景。
• 一致的响应格式：标准的 meta、data、warnings、error 信封结构。

验证与错误

• 缺少文件：image 字段为必填项，缺失则返回 400 错误。
• 无效格式：仅接受指定格式，其他格式返回 400 错误。
• 文件过大：图像超过10 MB将被拒绝，返回 400 错误。
• 未检测到面部：如果未检测到面部，data.faces 将为空数组（非错误）。
• 服务器错误：意外故障返回 500 状态码，错误详情在 error 字段中。
• 上游错误：如果分析服务超时或失败，则返回 502 错误。
• 错误响应格式：所有错误响应遵循相同信封结构：{ "meta": {...}, "data": null, "warnings": [], "error": { ... } }。