调用人脸属性检测接口检测图片中的人脸属性信息,具体包括人脸位置、性别、年龄、微笑程度、是否戴眼镜、人脸模糊度、人脸角度等。

  • 关于如何构造HTTP请求,请参见请求结构
  • 您也可以直接选用已构造好的HTTP请求,具体请参见SDK参考

描述

业务接口:/green/face/detect

成功调用人脸属性检测后,同步返回图片中的人脸属性信息。目前,支持检测的人脸属性包括人脸位置、性别、年龄、微笑程度、是否戴眼镜、人脸模糊度、人脸角度等。

针对图片中检测到的每个人脸,内容安全会判断人脸图片质量是否合格,并返回qualified参数供您参考。图片质量合格的判定规则是:人脸模糊度<5,且不佩戴墨镜,且人脸角度(包括人脸左右摇头角度、人脸抬头低头角度、人脸平面旋转角度)在30度内。您可以根据返回的人脸属性值,控制人脸质量,用作人脸底库质量管理等应用场景。

注意 该接口为计费接口。对于人脸属性检测功能,每检测一张图片计费一次,收费标准请参见计费方式

关于检测时长

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

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

请求参数

关于在请求中必须包含的公共请求参数,请参见公共参数

请求body是一个JSON对象,字段说明如下:

名称 类型 是否必须 描述
bizType 字符串 该字段用于标识业务场景。针对不同的业务场景,可以配置不同的算法策略。您可以通过云盾内容安全控制台创建业务场景(bizType),或者通过工单联系我们帮助您创建业务场景。
dataId 字符串 待检测图片的ID。如果该值不为空则会在响应中返回,您可以根据该值区分不同的图片。
url 字符串 要检测的人脸图片的url。

返回参数

返回结果说明,请参见返回结果

返回body中的data字段是JSON数组,每一个元素包含如下字段:

名称 类型 是否必须 描述
code 字符串 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 对应请求中的dataId
taskId 字符串 该检测任务的ID。
url 字符串 对应请求中的图片url。
faces JSON数组 调用成功时(code为200),返回的人脸属性信息。每个数组元素对应一张人脸,每个元素的结构描述见表 1
表 1. face
名称 类型 是否必须 描述
location Object 人脸的位置信息,具体结构描述见表 2
gender Object 人脸的性别信息,具体结构描述见表 3
age Object 人脸的年龄信息,具体结构描述见表 4
smile Object 人脸的微笑程度信息,具体结构描述见表 5
glasses Object 人脸的眼镜佩戴信息,具体结构描述见表 6
quality Object 人脸图片的质量信息,具体结构描述见表 7
qualified Boolean 人脸图片质量是否合格,取值:true/false。判定规则:人脸模糊度<5,且不佩戴墨镜,且人脸角度(包括人脸左右摇头角度、人脸抬头低头角度、人脸平面旋转角度)在30度内。该值仅作为参考。
表 2. location
名称 类型 是否必须 描述
x 浮点数 以图片左上角为坐标原点,人脸区域左上角到y轴的距离。
y 浮点数 以图片左上角为坐标原点,人脸区域左上角到x轴的距离。
w 浮点数 人脸区域的宽度。
h 浮点数 人脸区域的高度。
表 3. gender
名称 类型 是否必须 描述
value 字符串 人脸性别,取值:MaleFemale
rate 浮点数 性别结果的置信度,取值范围:0~1。值越高表示结果越可信。
表 4. age
名称 类型 是否必须 描述
value 整型 人脸年龄。
rate 浮点数 年龄结果的置信度,取值范围:0~1。值越高表示结果越可信。
表 5. smile
名称 类型 是否必须 描述
value 浮点数 人脸的微笑程度。
rate 浮点数 微笑结果的置信度,取值范围:0~1。值越高表示结果越可信。
表 6. glasses
名称 类型 是否必须 描述
value 字符串 人脸佩戴眼镜的情况,取值:
  • None:不戴眼镜
  • Wear:佩戴眼镜
  • Sunglass:佩戴墨镜
rate 浮点数 佩戴眼镜结果的置信度,取值范围:0~1。值越高表示结果越可信。
表 7. quality
名称 类型 是否必须 描述
blur 浮点数 人脸图片的模糊度,取值范围:0~20。分数越高表示越模糊。建议值:小于5。
pitch 浮点数 人脸的抬头/低头角度,建议值:-30~30。
yaw 浮点数 人脸的左右摇头角度,建议值:-30~30。
roll 浮点数 人脸的平面旋转角度,建议值:-30~30

示例

请求示例

{
  "bizType":"abc",
  "tasks": [
    {
      "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
      "url": "http://rifleman-share.oss-cn-hangzhou.aliyuncs.com/test/60767461_6.jpg"
    }
  ]
}

返回示例

{
  "code": 200,
  "data": {
    "code": 200,
    "faces": [
      {
        "age": {
          "rate": 0.99,
          "value": 38
        },
        "gender": {
          "rate": 0.99,
          "value": "Female"
        },
        "glasses": {
          "rate": 0.99,
          "value": "None"
        },
        "location": {
          "h": 101,
          "w": 101,
          "x": 32,
          "y": 206
        },
        "qualified": true,
        "quality": {
          "blur": 1.93,
          "pitch": -0.19,
          "roll": -3.84,
          "yaw": 27.19
        },
        "smile": {
          "rate": 0.99,
          "value": 0.65
        }
      }
    ],
    "msg": "OK",
    "taskId": "imgrUhAZhLr1o6qrpb4cA6Xk-1rauUl",
    "url": "http://abcxxxx.com/face1.jpeg"
  },
  "msg": "OK"
}