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

接口说明

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

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

  • 计费信息

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

  • 检测超时

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

  • 返回结果

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

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

请求参数

名称 类型 是否必选 描述
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"
}