文档

人脸属性检测API

更新时间:

本文介绍了调用人脸属性检测接口(/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)

      说明

      其中,GIF格式的图片,图像总像素不超过4,194,304(px),高度或者宽度不能超过30,000像素(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。

  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。

  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

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

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

人脸的微笑程度。取值范围:0~1。分数越高表示微笑程度越大。

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。取值越高表示结果越可信。

示例

请求示例

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"
}