本文介绍调用人脸属性检测API进行图片中人脸及人脸属性检测的方法。
一、功能介绍
人脸属性检测增强版能够识别图片中的人脸属性信息，包括人脸模糊度、人脸角度、人脸位置、微笑程度、是否戴眼镜、是否戴口罩、是否戴帽子、是否有胡子、是否有刘海、头发类型等。专业版支持检测图中人脸是否有夸张表情、是否有闭眼等属性。
|
服务（Service） |
检测说明 |
|
服务名：人脸属性检测 Service：faceDetect |
|
|
服务名：人脸属性检测_专业版 Service：faceDetect_pro |
|
二、计费说明
图片人脸属性检测增强版支持按量后付费和资源包抵扣两种付费方式。
按量后付费
当您开通内容安全增强版服务后，默认付费方式是按量后付费，且按照实际用量结算当日费用，不调用服务不收费。
|
审核类型 |
支持的业务场景（服务） |
计费单价 |
|
图片识别通用（image_standard） |
|
15元/万次 说明
调用1次左侧任一服务进行1次计费。根据实际调用量计费，如调用100次人脸属性检测计费0.15元。 |
|
图片识别高级（image_advanced） |
|
30元/万次 说明
调用1次左侧任一服务进行1次计费。根据实际调用量计费，如调用100次人脸属性检测专业版计费0.3元。 |
内容安全增强版的按量付费的计量出账频率为1小时/次。在出账详单中，moderationType对应上述审核类型字段。您可以查看账单详情。
资源包抵扣
如果您的识别量较大，或有相对固定的识别需求，建议预先购买资源包的方式。购买资源包规格越大，享受的折扣越大，支持叠加购买和使用。更多内容，请参见购买内容审核增强版抵扣资源包。
该资源包用于内容安全增强版用量的抵扣，无法与内容安全1.0版流量包共享，具体的抵扣系数如下：
|
审核类型 |
抵扣系数 |
|
图片识别通用（image_standard） |
2：即每成功调用一次接口，抵扣资源包的流量包容量规格2次。 例如购买的资源包的流量包容量规格为10次，当您成功调用1次接口，抵扣流量包容量规格2次，剩余8次。 |
|
图片审核高级（image_advanced） |
4：即每成功调用一次接口，抵扣资源包的流量包容量规格4次。 例如购买的资源包的流量包容量规格为10次，当您成功调用1次接口，抵扣流量包容量规格4次，剩余6次。 |
购买后，使用图片识别增强版API所产生的用量会优先抵扣资源包的次数，当资源包次数不足以抵扣时，阿里云费用系统会自动按照按量付费进行出账，请及时关注您的资源包余量和按量付费账单。您可以通过阿里云费用中心的资源包系统设定余量预警通知。
三、接入指引
-
注册阿里云账号：立即注册，按照操作提示完成账号注册。
-
开通内容安全按量付费：请确保您已开通服务，开通不收费，接口接入使用后系统会按使用量自动出账，详情请参见计费说明。您也可以购买按量抵扣资源包，资源包相较于后付费存在一定阶梯抵扣，适合使用量级可预期和较大的用户。
-
创建AccessKey：请确保您已通过RAM创建AccessKey，如果您使用的是子账号AccessKey，您需要通过主账号给子账号赋予AliyunYundunGreenWebFullAccess权限，具体操作，请参见RAM授权。
-
开发接入：推荐使用SDK方式调用，具体方法请详见图片审核增强版SDK及接入指南。
四、API接口
使用说明
您可以调用该接口创建图片内容检测任务。关于如何构造HTTP请求，请参见接入指南；您也可以直接选用已构造好的HTTP请求，更多信息，请参见SDK参考。
-
业务接口：ImageModeration
-
支持的地域及接入地址：
|
地域 |
外网接入地址 |
内网接入地址 |
支持服务 |
|
华东2（上海） |
https://green-cip.cn-shanghai.aliyuncs.com |
https://green-cip-vpc.cn-shanghai.aliyuncs.com |
faceDetect、faceDetect_pro |
|
华东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次/秒（专业版为5次/秒）。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。如果您业务量级较大或者有紧急扩容需求需要更大QPS，请联系您的商务经理。
调试
在接入前，您也可以通过阿里云OpenAPI在线调试图片审核增强版的接口，查看调用示例代码及SDK依赖信息，方便概览接口的使用方法和参数。
在线调试能力是基于当前登录账号调用内容安全的API接口，因此调用量会计入账号的收费用量中。
请求参数
关于在请求中必须包含的公共请求参数，请参考图片审核增强版SDK及接入指南。
请求body是一个JSON结构体，包含以下字段：
|
名称 |
类型 |
是否必选 |
示例值 |
描述 |
|
Service |
String |
是 |
faceDetect |
图片检测增强版支持的检测服务。取值：
|
|
ServiceParameters |
JSONString |
是 |
内容检测对象的相关参数集。JSON字符串格式，关于每个字符串的描述，请参见ServiceParameters。 |
表 1. ServiceParameters
|
名称 |
类型 |
是否必选 |
示例值 |
描述 |
|
imageUrl |
String |
是。图片识别增强版支持三种方式传入图片，请您选择其中一种：
|
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 |
是否佩戴眼镜的识别结果，取值：
|
|
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 |
是否佩戴口罩的识别结果，取值：
|
|
Confidence |
Float |
99.99 |
佩戴口罩结果的置信度，取值范围：0~100。取值越高表示结果越可信。 |
表 8.Hat
|
名称 |
类型 |
示例值 |
描述 |
|
Value |
String |
Wear |
是否佩戴帽子的识别结果，取值：
|
|
Confidence |
Float |
88.88 |
佩戴帽子结果的置信度，取值范围：0~100。取值越高表示结果越可信。 |
表 9.Mustache
|
名称 |
类型 |
示例值 |
描述 |
|
Value |
String |
None |
是否有胡须的识别结果，取值：
|
|
Confidence |
Float |
99.99 |
胡须识别结果的置信度，取值范围：0~100。取值越高表示结果越可信。 |
表 10.Bang
|
名称 |
类型 |
示例值 |
描述 |
|
Value |
String |
None |
是否有刘海的识别结果，取值：
|
|
Confidence |
Float |
81.88 |
刘海识别结果的置信度，取值范围：0~100。取值越高表示结果越可信。 |
表 11.Hairstyle
|
名称 |
类型 |
示例值 |
描述 |
|
Value |
String |
Short |
发型识别结果，取值：
|
|
Confidence |
Float |
81.88 |
发型识别结果的置信度，取值范围：0~100。取值越高表示结果越可信。 |
表 12.Gender
|
名称 |
类型 |
示例值 |
描述 |
|
Value |
String |
Male |
性别识别结果，取值：
|
|
Confidence |
Float |
81.88 |
性别识别结果的置信度，取值范围：0~100。取值越高表示结果越可信。 |
表 13. Result
|
名称 |
类型 |
示例值 |
描述 |
|
Label |
String |
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": 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": [
{
"Label": "face_exaggerated",
"Description": "图中人物有夸张表情",
"Confidence": 80.0
}
],
"RiskLevel": "high"
},
"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 |
系统异常。 |