本文介绍了调用人脸属性检测接口(/green/face/detect)进行图片人脸属性检测的方法。人脸属性检测能够识别图片中的人脸属性信息,包括人脸模糊度、人脸角度、人脸位置、微笑程度、是否戴眼镜、是否戴口罩、是否戴帽子、是否有胡子、是否有刘海、头发类型等。

使用说明

业务接口:/green/face/detect,表示人脸属性同步检测。

您可以调用该接口创建人脸属性检测任务并直接获得检测结果。关于如何构造HTTP请求,请参见请求结构;您也可以直接选用已构造好的HTTP请求,更多信息,请参见SDK概览

  • 计费信息

    该接口为收费接口。关于计费方式,请参见内容安全产品定价

  • 检测超时

    同步检测允许的最长检测时间是6秒,如果检测在该时间限制内没有完成,系统会强制返回超时错误码。如果您对实时性要求不高,可以选择异步检测,其他情况下请选择同步检测,同步检测接口的调用相对简单些。对于同步检测接口的调用,建议您将超时时间设置为6秒。

  • 返回结果

    同步检测请求一般会在一秒内同步返回结果,但在一些特殊场景(例如系统繁忙导致堆积严重、图片较大、含有OCR内容较多等),耗时可能会增加。

  • 图片要求
    • 图片链接支持以下协议:HTTP和HTTPS。
    • 图片支持以下格式:PNG、JPG、JPEG、BMP、GIF、WEBP。
    • 图片大小限制为20 MB以内(适用于同步和异步调用),高度或者宽度不能超过30,000像素(px),且图像总像素不超过2.5亿(px)
    • 图片下载时间限制为3秒内,如果下载时间超过3秒,返回下载超时。
    • 图片像素建议不低于256*256(px),像素过低可能会影响识别效果。
    • 图片检测接口的响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠,建议您使用阿里云OSS存储或者CDN缓存等。

QPS限制

本接口的单用户QPS限制为50次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。

请求参数

名称 类型 是否必选 描述
bizType String 该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景(具体操作,请参见自定义机审标准)。
dataId String 待检测图片的数据ID。如果该值不为空则会在响应中返回,您可以根据该值区分不同的图片。
url String 待检测图片的URL。

返回数据

名称 类型 描述
code String 错误码,和HTTP状态码一致。
msg String 错误描述信息。
dataId String 检测对象对应的数据ID。
说明 如果在检测请求参数中传入了dataId,则此处返回对应的dataId
taskId String 检测任务的ID。
url String 检测对象的URL。
faces JSONArray 调用成功时(code为200),返回的人脸属性信息,每个数组元素对应一张人脸。关于每个元素的结构描述,请参见face
表 1. face
名称 类型 描述
location JSONObject 人脸位置信息,具体结构描述,请参见location
smile JSONObject 人脸的微笑程度,具体结构描述,请参见smile
glasses JSONObject 是否佩戴眼镜的识别结果,具体结构描述,请参见glasses
quality JSONObject 人脸图片的质量信息,具体结构描述,请参见quality
qualified Boolean 人脸图片质量是否合格,取值:
  • true:合格。
  • false:不合格。
针对图片中检测到的每个人脸,内容安全会判断人脸图片质量是否合格。合格的人脸图片必须同时满足以下条件:
  • 人脸模糊度小于5。
  • 未佩戴墨镜。
  • 人脸角度(包括人脸左右摇头角度、人脸抬头低头角度、人脸平面旋转角度)在30度以内。

您可以根据返回的人脸属性值控制人脸图片质量,用作人脸底库质量管理等场景。

respirator JSONObject 是否佩戴口罩的识别结果,具体结构描述,请参见respirator
hat JSONObject 是否佩戴帽子的识别结果,具体结构描述,请参见hat
mustache JSONObject 是否有胡子的识别结果,具体结构描述,请参见mustache
bang JSONObject 是否有刘海的识别结果,具体结构描述,请参见bang
hairstyle JSONObject 发型识别结果,具体结构描述,请参见hairstyle
表 2. location
名称 类型 描述
x Float 以图片左上角为坐标原点,人脸区域左上角到y轴的距离,单位:像素。
y Float 以图片左上角为坐标原点,人脸区域左上角到x轴的距离,单位:像素。
w Float 人脸区域的宽度,单位:像素。
h Float 人脸区域的高度,单位:像素。
表 3. smile
名称 类型 描述
value Float 人脸的微笑程度。
rate Float 微笑结果的置信度,取值范围:0~1。取值越高表示结果越可信。
表 4. glasses
名称 类型 描述
value String 是否佩戴眼镜的识别结果,取值:
  • None:未佩戴眼镜。
  • Wear:佩戴眼镜。
  • Sunglass:佩戴墨镜。
rate Float 佩戴眼镜结果的置信度,取值范围:0~1。取值越高表示结果越可信。
表 5. quality
名称 类型 描述
blur Float 人脸图片的模糊度,取值范围:0~20。分数越高表示越模糊。

建议取值范围:0~5。

pitch Float 人脸的抬头或低头角度。

建议取值范围:-30~30。

yaw Float 人脸的左右摇头角度。

建议取值范围:-30~30。

roll Float 人脸的平面旋转角度。

建议取值范围:-30~30。

表 6. respirator
名称 类型 描述
value String 是否佩戴口罩的识别结果,取值:
  • Wear:佩戴口罩。
  • None:未佩戴口罩。
rate Float 佩戴口罩结果的置信度,取值范围:0~1。取值越高表示结果越可信。
表 7. hat
名称 类型 描述
value String 是否佩戴帽子的识别结果,取值:
  • Wear:佩戴帽子。
  • None:未佩戴帽子。
rate Float 佩戴帽子结果的置信度,取值范围:0~1。取值越高表示结果越可信。
表 8. mustache
名称 类型 描述
value String 是否有胡须的识别结果,取值:
  • Has:有胡须。
  • None:无胡须。
rate Float 胡须识别结果的置信度,取值范围:0~1。取值越高表示结果越可信。
表 9. bang
名称 类型 描述
value String 是否有刘海的识别结果,取值:
  • Has:有刘海。
  • None:无刘海。
rate Float 刘海识别结果的置信度,取值范围:0~1。取值越高表示结果越可信。
表 10. hairstyle
名称 类型 描述
value String 发型识别结果,取值:
  • Bald:光头。
  • Long:长发。
  • Short:短发。
rate Float 发型识别结果的置信度,取值范围:0~1。取值越高表示结果越可信。

示例

请求示例

{
      "bizType": "abc",
      "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
      "url": "http://example.com/face1.jpeg"
}

正常返回示例

{
     "msg": "OK",
     "code": 200,
     "extras": {
          "width": "328",
          "height": "390"
    },
     "faces": [
          {
               "glasses": {
                    "rate": 0.99,
                    "value": "None"
            },
               "qualified": false,
               "bang": {
                    "rate": 0.99,
                    "value": "Has"
            },
               "respirator": {
                    "rate": 0.99,
                    "value": "None"
            },
               "hat": {
                    "rate": 0.99,
                    "value": "None"
            },
               "location": {
                    "w": 116,
                    "h": 116,
                    "x": 134,
                    "y": 135
            },
               "mustache": {
                    "rate": 0.99,
                    "value": "None"
            },
               "hairstyle": {
                    "rate": 0.99,
                    "value": "Short"
            },
               "quality": {
                    "roll": 0.38,
                    "blur": 6.44,
                    "pitch": 21.21,
                    "yaw": 21.12
            },
               "smile": {
                    "rate": 0.99,
                    "value": 0.5
            }
        }
    ],
     "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
     "taskId": "img1uJtIrlwH$F4FA3h$Sxe2F-1tbWWx",
     "url": "http://example.com/face1.jpeg"
}