Skip to main content
POST
/
portrait
/
analysis
/
face-analysis
Face Analysis
curl --request POST \
  --url https://api.aihairstyle.cn/portrait/analysis/face-analysis \
  --header 'Content-Type: multipart/form-data' \
  --header 'ailabapi-api-key: <api-key>' \
  --form task_type=async \
  --form image=@example-file
{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  },
  "result": {
    "face_num": 123,
    "face_info": [
      {
        "face_rect": {
          "left": 123,
          "top": 123,
          "width": 123,
          "height": 123
        },
        "face_angle": {
          "yaw": 123,
          "pitch": 123,
          "roll": 123
        },
        "face_proportion": 123
      }
    ]
  }
}

请求

  • URL: /portrait/analysis/face-analysis
  • 方法: POST

人脸分析 API

分析图片中的人脸信息,包括人脸数量、位置、角度等,用于前端验证和图片质量检查。

功能特点

  • 人脸检测:准确检测图片中的人脸数量
  • 位置分析:获取人脸在图片中的精确位置
  • 角度分析:分析人脸的偏航角、俯仰角、翻滚角
  • 比例计算:计算人脸在图片中的占比
  • 质量评估:评估图片是否适合发型编辑

应用场景

  • 前端验证:在用户上传图片前进行质量检查
  • 图片预处理:根据人脸位置进行智能裁剪
  • 质量筛选:过滤不符合要求的图片
  • 用户体验:提供即时的图片质量反馈

图片要求

为了获得准确的检测结果,请确保上传的图片符合以下要求:
  • 图片中必须包含清晰的人脸
  • 人脸不应被严重遮挡或模糊
  • 光线充足,避免过暗或过亮
  • 图片分辨率建议不低于 200x200 像素

支持的图片格式

  • 格式:PNG、JPG、JPEG
  • 大小:不超过 3MB
  • 分辨率:200x200px ~ 1999x1999px

异步处理流程

对于异步任务,完整的处理流程如下:
  1. 提交任务:调用 API 提交处理任务
  2. 获取 task_id:API 返回 task_id
  3. 查询结果:使用 task_id 查询处理结果
  4. 获取最终结果:当任务完成时获取最终结果

响应示例(异步任务查询API获取)

成功响应

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "result": {
    "face_num": 1,
    "face_info": [
      {
        "face_rect": {
          "left": 100,
          "top": 50,
          "width": 200,
          "height": 250
        },
        "face_angle": {
          "yaw": 5.2,
          "pitch": -2.1,
          "roll": 1.8
        },
        "face_proportion": 0.35
      }
    ]
  }
}

错误响应

{
  "request_id": "123456789",
  "log_id": "987654321",
  "error_code": 422,
  "error_msg": "No face detected in the file",
  "error_detail": {
    "status_code": 422,
    "code": "ERROR_NO_FACE_IN_FILE",
    "code_message": "No face detected in the file",
    "message": "pic not has face"
  }
}

响应字段说明

主要字段

字段类型说明
face_numinteger检测到的人脸数量
face_infoarray人脸信息数组

人脸信息字段

字段类型说明
face_rectobject人脸矩形区域
face_angleobject人脸角度信息
face_proportionnumber人脸占比

矩形区域字段

字段类型说明
leftinteger左边界坐标
topinteger上边界坐标
widthinteger宽度
heightinteger高度

角度字段

字段类型说明有效范围
yawnumber偏航角(左右转动)±45°
pitchnumber俯仰角(上下点头)±30°
rollnumber翻滚角(左右倾斜)±30°

验证标准

人脸数量验证

// 检查人脸数量
if (result.result.face_num === 0) {
  throw new Error('未检测到人脸');
} else if (result.result.face_num > 1) {
  throw new Error('检测到多个人脸,请使用单人照片');
}

人脸占比验证

// 检查人脸占比
const faceInfo = result.result.face_info[0];
const faceProportion = faceInfo.face_proportion;

if (faceProportion < 0.2) {
  throw new Error('人脸占比过小,请使用更近的照片');
} else if (faceProportion > 0.8) {
  throw new Error('人脸占比过大,请使用更远的照片');
}

人脸角度验证

// 检查人脸角度
const { yaw, pitch, roll } = faceInfo.face_angle;

if (Math.abs(yaw) > 45 || Math.abs(pitch) > 30 || Math.abs(roll) > 30) {
  throw new Error('人脸角度过大,请使用正面照片');
}

最佳实践

1. 前端验证流程

async function validateImage(imageFile) {
  // 1. 调用人脸分析 API
  const analysisResult = await analyzeFace(imageFile);
  
  // 2. 检查人脸数量
  if (analysisResult.face_num !== 1) {
    throw new Error('请使用包含且仅包含一个人脸的照片');
  }
  
  // 3. 检查人脸占比
  const faceInfo = analysisResult.face_info[0];
  if (faceInfo.face_proportion < 0.2 || faceInfo.face_proportion > 0.8) {
    throw new Error('人脸占比应在20%-80%之间');
  }
  
  // 4. 检查人脸角度
  const { yaw, pitch, roll } = faceInfo.face_angle;
  if (Math.abs(yaw) > 45 || Math.abs(pitch) > 30 || Math.abs(roll) > 30) {
    throw new Error('请使用正面照片,人脸角度不应过大');
  }
  
  return true;
}

相关链接

Authorizations

ailabapi-api-key
string
header
required

API Key for authentication

Body

multipart/form-data
task_type
enum<string>
default:async
required

Task Type. async: Asynchronous task.

Available options:
async
image
file
required

Image file for face analysis (PNG/JPG/JPEG). ≤3MB, 200x200~1999x1999.

Response

Success

request_id
string

Request ID

log_id
string

Log ID

error_code
integer

Status code (0 for success)

error_msg
string

Error message

error_detail
object
result
object