本文介绍了调用人脸属性检测接口(/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调用会被限流,这可能会影响您的业务,请合理调用。

请求参数

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

返回数据

名称类型描述
codeString错误码,和HTTP状态码一致。
msgString错误描述信息。
dataIdString检测对象对应的数据ID。
说明 如果在检测请求参数中传入了dataId,则此处返回对应的dataId
taskIdString检测任务的ID。
urlString
检测对象的URL。
  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。
  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

    文件路径格式:oss://<bucket-name>.<endpoint>/<object-name>

facesJSONArray调用成功时(code为200),返回的人脸属性信息,每个数组元素对应一张人脸。关于每个元素的结构描述,请参见face
表 1. face
名称类型描述
locationJSONObject人脸位置信息,具体结构描述,请参见location
smileJSONObject人脸的微笑程度,具体结构描述,请参见smile
glassesJSONObject是否佩戴眼镜的识别结果,具体结构描述,请参见glasses
qualityJSONObject人脸图片的质量信息,具体结构描述,请参见quality
qualifiedBoolean人脸图片质量是否合格,取值:
  • true:合格。
  • false:不合格。
针对图片中检测到的每个人脸,内容安全会判断人脸图片质量是否合格。合格的人脸图片必须同时满足以下条件:
  • 人脸模糊度小于5。
  • 未佩戴墨镜。
  • 人脸角度(包括人脸左右摇头角度、人脸抬头低头角度、人脸平面旋转角度)在30度以内。

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

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

建议取值范围:0~5。

pitchFloat人脸的抬头或低头角度。

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

yawFloat人脸的左右摇头角度。

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

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

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

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

示例

请求示例

http(s)://[Endpoint]/green/face/detect
&<公共请求参数>
{
      "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"
}