如何调用人脸属性检测接口_内容安全(Content Moderation)-阿里云帮助中心

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