文档

人脸属性检测增强版

更新时间:

本文介绍调用人脸属性检测API进行图片中人脸及人脸属性检测的方法。

一、功能介绍

人脸属性检测能够识别图片中的人脸属性信息,包括人脸模糊度、人脸角度、人脸位置、微笑程度、是否戴眼镜、是否戴口罩、是否戴帽子、是否有胡子、是否有刘海、头发类型等。

服务(Service)

检测说明

服务名:人脸属性检测

Service:faceDetect

  • 能识别图片中的多个人脸属性,默认最多可检测5个人脸

  • 支持返回人脸多个属性,详细返回信息,请参考返回数据

二、计费说明

图片人脸属性检测增强版支持按量后付费和资源包抵扣两种付费方式。

按量后付费

当您开通内容安全增强版服务后,默认付费方式是按量后付费,且按照实际用量结算当日费用,不调用服务不收费。

审核类型

支持的业务场景(服务)

计费单价

图片识别通用(image_standard)

  • 人脸属性检测:faceDetect

15元/万次

说明

调用1次左侧任一服务进行1次计费。根据实际调用量计费,如调用100次人脸属性检测计费0.15元。

说明

内容安全增强版的按量付费的计量出账频率为1小时/次。在出账详单中,moderationType对应上述审核类型字段。您可以查看账单详情

资源包抵扣

如果您的识别量较大,或有相对固定的识别需求,建议预先购买资源包的方式。购买资源包规格越大,享受的折扣越大,支持叠加购买和使用。更多内容,请参见购买内容审核增强版抵扣资源包

该资源包用于内容安全增强版用量的抵扣,无法与内容安全1.0版流量包共享,具体的抵扣系数如下:

审核类型

支持的业务场景(服务)

抵扣系数

图片识别通用(image_standard)

  • 人脸属性检测:faceDetect

2:即每成功调用一次接口,抵扣资源包的流量包容量规格2次。

例如购买的资源包的流量包容量规格为10次,当您成功调用1次接口,抵扣流量包容量规格2次,剩余8次。

购买后,使用图片识别增强版API所产生的用量会优先抵扣资源包的次数,当资源包次数不足以抵扣时,阿里云费用系统会自动按照按量付费进行出账,请及时关注您的资源包余量和按量付费账单。您可以通过阿里云费用中心的资源包系统设定余量预警通知。

三、接入指引

  1. 注册阿里云账号:立即注册,按照操作提示完成账号注册。

  2. 开通内容安全按量付费:请确保您已开通服务,开通不收费,接口接入使用后系统会按使用量自动出账,详情请参见计费说明。您也可以购买按量抵扣资源包,资源包相较于后付费存在一定阶梯抵扣,适合使用量级可预期和较大的用户。

  3. 创建AccessKey:请确保您已通过RAM创建AccessKey,如果您使用的是子账号AccessKey,您需要通过主账号给子账号赋予AliyunYundunGreenWebFullAccess权限,具体操作,请参见RAM授权

  4. 开发接入:推荐使用SDK方式调用,具体方法请详见图片审核增强版SDK及接入指南

四、API接口

使用说明

您可以调用该接口创建图片内容检测任务。关于如何构造HTTP请求,请参见接入指南;您也可以直接选用已构造好的HTTP请求,更多信息,请参见SDK参考

  • 业务接口:ImageModeration

  • 支持的地域及接入地址

地域

外网接入地址

内网接入地址

支持服务

华东2(上海)

https://green-cip.cn-shanghai.aliyuncs.com

https://green-cip-vpc.cn-shanghai.aliyuncs.com

faceDetect

华东1(杭州)

https://green-cip.cn-hangzhou.aliyuncs.com

https://green-cip-vpc.cn-hangzhou.aliyuncs.com

  • 计费信息:该接口为收费接口。仅对HTTP状态码为200的请求进行计量计费,产生其他错误码时不会计费。关于计费方式,请参见计费说明

  • 图片要求

  • 图片支持以下格式:PNG、JPG、JPEG、BMP、WEBP、TIFF、SVG、HEIC(该格式最长边需小于8192 px)、GIF(取第一帧)、ICO(取最后一图)。

  • 图片大小限制在20 MB以内,高或者宽不能超过16,384 px,且总像素不能超过1.67亿 px。像素建议大于200*200(px),像素过低会影响内容安全检测算法的效果。

  • 图片下载时间限制为3秒内,如果下载时间超过3秒,返回下载超时。

QPS限制

本接口的单用户QPS限制为10次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。如果您业务量级较大或者有紧急扩容需求需要更大QPS,请联系您的商务经理。

调试

在接入前,您也可以通过阿里云OpenAPI在线调试图片审核增强版的接口,查看调用示例代码及SDK依赖信息,方便概览接口的使用方法和参数。

重要

在线调试能力是基于当前登录账号调用内容安全的API接口,因此调用量会计入账号的收费用量中。

请求参数

关于在请求中必须包含的公共请求参数,请参考图片审核增强版SDK及接入指南

请求body是一个JSON结构体,包含以下字段:

名称

类型

是否必选

示例值

描述

Service

String

faceDetect

图片检测增强版支持的检测服务。取值:

  • faceDetect 人脸属性检测

ServiceParameters

JSONString

内容检测对象的相关参数集。JSON字符串格式,关于每个字符串的描述,请参见ServiceParameters

表 1. ServiceParameters

名称

类型

是否必选

示例值

描述

imageUrl

String

是。图片识别增强版支持三种方式传入图片,请您选择其中一种:

  • 使用图片URL方式进行检测,传入imageUrl。

  • 使用OSS授权进行检测,必须同时传入ossBucketName、ossObjectName、ossRegionId。

  • 使用本地图片进行检测。上传本地图片检测,不占用您的OSS存储空间,且文件只存储30分钟。SDK接入已经集成本地图片上传功能,具体代码示例,请参见图片审核增强版SDK及接入指南

https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png

待检测对象的URL,请确保该URL能通过公网访问到,且URL地址长度不超过2048个字符。

说明

URL地址中不能包含中文,且一次请求请确保仅传入1条URL。

ossBucketName

String

bucket_01

已授权OSS空间的Bucket名。

说明

使用OSS图片内网地址时必须先使用阿里云账号(即主账号)访问云资源访问授权页面进行授权。

ossObjectName

String

20240307/04/24/test.jpg

已授权OSS空间的文件名。

ossRegionId

String

cn-beijing

OSS Bucket所在区域。

dataId

String

img123****

检测对象对应的数据ID。

由大小写英文字母、数字、下划线(_)、短划线(-)、英文句号(.)组成,不超过64个字符,可以用于唯一标识您的业务数据。

referer

String

www.aliyun.com

referer请求头,用于防盗链等场景。长度不超过256个字符。

返回数据

名称

类型

示例值

描述

RequestId

String

70ED13B0-BC22-576D-9CCF-1CC12FEAC477

本次调用请求的ID,是由阿里云为该请求生成的唯一标识符,可用于排查和定位问题。

Data

Object

图片内容检测结果。更多信息,请参见Data

Code

Integer

200

状态码。更多信息,请参见Code说明

Msg

String

OK

本次请求的响应消息。

表 2. Data

名称

类型

示例值

描述

Ext

Object

人脸属性检测结果。更多信息,请参见Ext

DataId

String

img123******

检测对象对应的数据ID。

说明

如果在检测请求参数中传入了dataId,则此处返回对应的dataId。

Result

Array

图片审核的风险标签、置信分等参数结果。更多信息,请参见Result

说明

使用人脸属性检测时,该返回值暂时可以忽略。

表 3. Ext

名称

类型

示例值

描述

FaceData

Array

人脸属性检测结果。更多信息,请参见FaceData

表 4. FaceData

名称

类型

示例值

描述

Location

JSONObject

人脸位置信息,具体结构描述,请参见Location

Smile

Float

85.88

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

Glasses

String

None

是否佩戴眼镜的识别结果,取值:

  • None:未佩戴眼镜。

  • Common:佩戴普通眼镜。

  • Sunglass:佩戴太阳镜。

Age

Integer

18

年龄识别结果。

Quality

JSONObject

人脸图片的质量信息,具体结构描述,请参见Quality

Mask

JSONObject

是否佩戴口罩的识别结果,具体结构描述,请参见Mask

Hat

JSONObject

是否佩戴帽子的识别结果,具体结构描述,请参见Hat

Mustache

JSONObject

是否有胡子的识别结果,具体结构描述,请参见Mustache

Bang

JSONObject

是否有刘海的识别结果,具体结构描述,请参见Bang

Hairstyle

JSONObject

发型识别结果,具体结构描述,请参见Hairstyle

Gender

JSONObject

性别识别结果,具体结构描述,请参见Gender

表 5.Location

名称

类型

示例值

描述

X

Float

41

以图片左上角为坐标原点,人脸区域左上角到y轴的距离,单位:像素。

Y

Float

84

以图片左上角为坐标原点,人脸区域左上角到x轴的距离,单位:像素。

W

Float

83

人脸区域的宽度,单位:像素。

H

Float

26

人脸区域的高度,单位:像素。

表 6.Quality

名称

类型

示例值

描述

Blur

Float

5.88

人脸图片的模糊度,取值范围:0~100。分数越高表示越模糊。

建议取值范围:0~25。

Integrity

Float

100.0

人脸的完整度,取值范围:0~100。分数越高表示越完整。

建议取值范围:80~100。

Pitch

Float

5.88

人脸的抬头或低头角度。

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

Yaw

Float

5.18

人脸的左右摇头角度。

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

Roll

Float

5.18

人脸的平面旋转角度。

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

表 7.Mask

名称

类型

示例值

描述

Value

String

None

是否佩戴口罩的识别结果,取值:

  • Wear:佩戴口罩。

  • None:未佩戴口罩。

Confidence

Float

99.99

佩戴口罩结果的置信度,取值范围:0~100。取值越高表示结果越可信。

表 8.Hat

名称

类型

示例值

描述

Value

String

Wear

是否佩戴帽子的识别结果,取值:

  • Wear:佩戴帽子。

  • None:未佩戴帽子。

Confidence

Float

88.88

佩戴帽子结果的置信度,取值范围:0~100。取值越高表示结果越可信。

表 9.Mustache

名称

类型

示例值

描述

Value

String

None

是否有胡须的识别结果,取值:

  • Has:有胡须。

  • None:无胡须。

Confidence

Float

99.99

胡须识别结果的置信度,取值范围:0~100。取值越高表示结果越可信。

表 10.Bang

名称

类型

示例值

描述

Value

String

None

是否有刘海的识别结果,取值:

  • Has:有刘海。

  • None:无刘海。

Confidence

Float

81.88

刘海识别结果的置信度,取值范围:0~100。取值越高表示结果越可信。

表 11.Hairstyle

名称

类型

示例值

描述

Value

String

Short

发型识别结果,取值:

  • Bald:光头。

  • Long:长发。

  • Short:短发。

Confidence

Float

81.88

发型识别结果的置信度,取值范围:0~100。取值越高表示结果越可信。

表 12.Gender

名称

类型

示例值

描述

Value

String

Male

性别识别结果,取值:

  • Male:男性。

  • FeMale:女性。

Confidence

Float

81.88

性别识别结果的置信度,取值范围:0~100。取值越高表示结果越可信。

表 13. Result

名称

类型

示例值

描述

Label

String

nonLabel

图片检测运算后返回的标签。人脸属性检测场景默认返回nonLabel,无需处理该标签。

Confidence

Float

99.99

置信分值,0到100分,保留到小数点后2位。返回nonLabel时无置信分。

示例

请求示例

{
    "Service": "faceDetect",
    "ServiceParameters": {
        "imageUrl": "https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png",
        "dataId": "test0307****"
    }
}

返回示例

{
    "Code": 200,
    "Data": {
        "DataId": "test0307****",
        "Ext": {
            "FaceData": [
                {
                    "Age": 24,
                    "Bang": {
                        "Confidence": 100.0,
                        "Value": "None"
                    },
                    "Gender": {
                        "Confidence": 95.72,
                        "Value": "Male"
                    },
                    "Glasses": "None",
                    "Hairstyle": {
                        "Confidence": 98.23,
                        "Value": "Short"
                    },
                    "Hat": {
                        "Confidence": 99.99,
                        "Value": "None"
                    },
                    "Location": {
                        "H": 98,
                        "W": 98,
                        "X": 550,
                        "Y": 251
                    },
                    "Mask": {
                        "Confidence": 99.99,
                        "Value": "None"
                    },
                    "Mustache": {
                        "Confidence": 99.58,
                        "Value": "None"
                    },
                    "Quality": {
                        "Blur": 13.72,
                        "Integrity": 100.0,
                        "Pitch": 5.84,
                        "Roll": 3.66,
                        "Yaw": 21.22
                    },
                    "Smile": 82.49
                }
            ]
        },
        "Result": [
            {
                "Confidence": null,
                "Description": "未检测出风险",
                "Label": "nonLabel"
            }
        ],
        "RiskLevel": "none"
    },
    "Msg": "success",
    "RequestId": "TEST001-2024-0307-0728-5201314YHX"
}
说明

文档中的请求示例和返回示例为了便于阅读,做了格式化处理,实际返回结果是没有进行换行、缩进等处理。

Code说明

以下为接口返回code的含义说明,系统仅对code返回为200的请求计量计费,其他code不会计费。

Code

说明

200

请求正常。

400

请求参数为空。

401

请求参数错误。

402

请求参数长度不符合接口规定,请检查并修改。

403

请求超过QPS限制,请检查并调整并发。

404

传入的图片下载遇到错误,请检查或重试。

405

传入的图片下载超时,可能是因为图片无法访问,请检查调整后重试。

406

传入的图片过大,请检查调整图片大小后再重试。

407

传入的图片格式暂不支持,请检查调整后重试。

408

该账号无权限调用该接口,可能是账号未开通或者已欠费,或者调用账号未被授权访问。

500

系统异常。