文档首页/ 人脸识别服务 FRS/ API参考/ API/ 人脸检测
更新时间：2024-04-19 GMT+08:00
查看PDF
分享

人脸检测

功能介绍

人脸检测是对输入图片进行人脸检测和分析，输出人脸在图像中的位置。若照片中存在多张人脸，则返回所有符合条件的人脸特征信息。

前提条件：

请确保您已开通人脸识别服务，具体操作方法请参见申请服务。

约束限制：
  • 只支持识别JPG、PNG、JPEG、BMP格式的图片。
  • application/json请求的body中，请使用标准Json格式。
  • Base64编码中请勿使用回车换行。
  • 系统不保存用户图片。
  • 图片大小小于8MB，由于过大图片会导致时延较长，并且图片信息量不大，建议小于1MB。
  • 图片分辨率小于4096*2160，图片中人脸像素大于80*80，建议120*120以上。
  • 为保证识别效果，人脸图片建议要求如下：
    1. 光照大于200lux、无反光强光阴影现象。
    2. 人脸无遮挡、整体清晰无拖尾抖动等运动模糊。
    3. 侧脸不超过30°、俯仰角小于15°、偏转角小于15°、图片中人脸保持竖置正脸。
  • 其他的约束限制信息请参见约束与限制章节。
建议：
  • 由于过大图片对识别算法精度无明显提升，同时会导致时延较长，建议传入图片小于1MB，一般500KB左右足够。
  • OBS上存储的图片也建议小于1MB。
  • 图片中人脸像素建议120*120以上。

URI

POST /v2/{project_id}/face-detect

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID，获取方法请参见获取项目ID/账号名/AK/SK。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限，响应消息头中X-Subject-Token的值即为Token。

Content-Type

是

String

发送的实体的MIME类型，参数值为“application/json”。
表3 请求Body参数

参数名

是否必选

参数类型

说明

image_url

与image_file、image_base64三选一

String

图片的URL路径，目前仅支持华为云上OBS的URL，且人脸识别服务有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权。

image_file

与image_url、image_base64三选一

File

本地图片文件，图片不能超过8MB，建议小于1MB。上传文件时，请求格式为multipart。

image_base64

与image_file、image_url三选一

String
图像数据，Base64编码，要求：
  • Base64编码后大小不超过8MB，建议小于1MB。
  • 图片为JPG/JPEG/BMP/PNG格式。

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

faces

Array of DetectFace objects

检测到的人脸。 调用失败时无此字段。
表5 DetectFace

参数

参数类型

描述

bounding_box

BoundingBox object

人脸在图像中的位置。
表6 BoundingBox

参数

参数类型

描述

width

Integer

矩形框宽度。

top_left_y

Integer

矩形框左上角纵坐标。

top_left_x

Integer

矩形框左上角横坐标。

height

Integer

矩形框高度。

状态码： 400

表7 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码。 调用成功时无此字段。

error_msg

String

调用失败时的错误信息。 调用成功时无此字段。

请求示例

X-Auth-Token值获取方法请参见认证鉴权。

  • 请求样例（方式一：使用图片的BASE64编码） 
    POST https://{endpoint}/v2/{project_id}/face-detect
Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:
{
    "image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD"
    
}
  • 请求样例（方式二：使用图片文件） 
    POST https://{endpoint}/v2/{project_id}/face-detect
Request Header:
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:
  image_file: File(图片文件)
  • 请求样例（方式三：使用图片URL） 
    POST https://{endpoint}/v2/{project_id}/face-detect
Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:
{
    "image_url": "/BucketName/ObjectName"
    
}

响应示例

状态码：200

成功响应样例 
{
  "faces": [
    {
      "bounding_box": {
        "width": 174,
        "top_left_y": 37,
        "top_left_x": 22,
        "height": 174
      }
    }
  ]
}

状态码：400

失败响应样例 
{
  "error_code": "FRS.0019",
  "error_msg": "The service has not been subscribed."
}

状态码

状态码请参见状态码。

错误码

错误码请参见错误码。

父主题： API