调用DetectFaceAttributes检测人脸照片中的有效性属性。

请求方法:仅支持以HTTPS POST方法发送请求。

接口描述:对输入照片中人脸的有效性相关属性进行检测,便于业务方判定该照片是否满足自身业务留存或比对的要求。目前支持的人脸有效性相关属性有:是否人脸、是否模糊、是否戴眼镜、脸部姿态、是否笑脸等。

上传图片地址的说明:在传入图片时,您需要上传其对应的HTTP、OSS地址或本地文件。

  • HTTP地址:可访问的公网HTTP地址。例如,http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg。
  • 本地文件:传入本地图片时,可以使用图片的相对路径或绝对路径。

图片限制:

  • 支持传入本地图片。传入本地图片时,可以使用图片的相对路径或绝对路径。
  • 单张图片大小请控制在2 MB及以下,避免算法拉取超时。

本文是最新版的接口文档,如果您需要查看之前版本,请参见DetectFaceAttributes

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String DetectFaceAttributes

要执行的操作。取值:DetectFaceAttributes。

BizId String 39ecf51e-2f81-4dc5-90ee-ff86125be683

认证ID。标识一次认证任务的唯一ID,不超过64字符。

说明 发起不同的认证任务时需要更换不同的BizId。
BizType String RPBasicTest

使用实人认证服务的业务场景标识。关于如何通过控制台创建BizType,请参见添加业务场景

ImageFile String \xxx\xxx.JPG

认证的本地资源文件。

如果您使用本地资源文件进行人脸属性检测,请参见SDK调用示例。目前该方式仅支持SDK调用。

说明 ImageUrl和ImageFile二选一。
ImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg

认证的资源地址。公网可访问的HTTP、HTTPS链接。

说明 ImageUrl和ImageFile二选一。

返回数据

名称 类型 示例值 描述
Code String 200

HTTP状态码。

Message String success

请求信息的响应消息。

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

本次请求的ID。

ResultObject Struct

检测结果。

FaceInfos Array of FaceAttributesDetectInfo

人脸检测结果。

FaceAttributesDetectInfo
FaceAttributes Struct

人脸属性。

Blur Float 0.1419367790222168

人脸模糊度,分值越大越模糊。通常大于等于2.0表示较模糊,建议根据实际业务数据测试调整。

Facequal Float 60

表示分数,取值范围:0~100。分数越高,质量越好,建议您使用大于或者等于50分认为质量合格。

Facetype String Face

是否是人脸。取值:

  • None:不是人脸
  • Face:人脸
  • Profile:侧脸(左右转头超过30°)
说明 若没有检测到人脸,接口返回的faceInfos即为空;这里的None代表检测到人脸,但认为是卡通或宠物等。
Glasses String None

是否戴眼镜。取值:

  • None:未戴眼镜
  • Wear:戴普通眼镜
  • Sunglass:戴墨镜
Headpose Struct

人脸姿态。

PitchAngle Float -1.5683923959732056

抬头角度,单位为度。

RollAngle Float 7.163370132446289

左右歪头角度,单位为度。

YawAngle Float -6.925303936004639

左右转头角度,单位为度。

Integrity Integer 70

表示分数,取值范围:0~100。分数越高,人脸越完整,建议您使用大于等于70分为完整度合格。

Respirator String Wear

是否戴口罩。取值:

  • Wear:表示戴口罩。
  • None:表示没有戴口罩。
Smiling Struct

是否笑脸。

Threshold Float 95

笑脸阈值。

Value Float 97

笑脸分值。

FaceRect Struct

人脸在原图中的位置。

Height Integer 473

人脸矩形的高度。

Left Integer 354

人脸矩形左上角距原图左边的距离,单位为像素。

Top Integer 453

人脸矩形左上角距原图上边的距离,单位为像素。

Width Integer 473

人脸矩形的宽度。

ImgHeight Integer 1920

原图高度,单位为像素。

ImgWidth Integer 1080

原图宽度,单位为像素。

Success Boolean true

是否成功响应。

  • true:响应成功。
  • false:响应失败。

示例

请求示例

http(s)://[Endpoint]/?Action=DetectFaceAttributes
&BizId=39ecf51e-2f81-4dc5-90ee-ff86125be683
&BizType=RPBasicTest
&ImageFile=FileInputStream
&ImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
&<公共请求参数>

正常返回示例

XML格式

<DetectFaceAttributesResponse>
	  <ResultObject>
		    <ImgWidth>1080</ImgWidth>
		    <ImgHeight>1920</ImgHeight>
		    <FaceInfos>
			      <FaceAttributesDetectInfo>
				        <FaceRect>
					          <Left>354</Left>
					          <Top>453</Top>
					          <Height>473</Height>
					          <Width>473</Width>
				        </FaceRect>
				        <FaceAttributes>
					          <Facetype>Face</Facetype>
					          <Respirator>Wear</Respirator>
					          <Blur>0.1419367790222168</Blur>
					          <Glasses>None</Glasses>
					          <AppearanceScore></AppearanceScore>
					          <Facequal>60</Facequal>
					          <Integrity>70</Integrity>
					          <Smiling>
						            <Value>97</Value>
						            <Threshold>95</Threshold>
					          </Smiling>
					          <Headpose>
						            <PitchAngle>-1.5683923959732056</PitchAngle>
						            <RollAngle>7.163370132446289</RollAngle>
						            <YawAngle>-6.925303936004639</YawAngle>
					          </Headpose>
				        </FaceAttributes>
			      </FaceAttributesDetectInfo>
		    </FaceInfos>
	  </ResultObject>
	  <Message>success</Message>
	  <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
	  <Code>200</Code>
	  <Success>true</Success>
  </DetectFaceAttributesResponse>

JSON格式

{
	"ResultObject": {
		"ImgWidth": "1080",
		"ImgHeight": "1920",
		"FaceInfos": {
			"FaceAttributesDetectInfo": [{
				"FaceRect": {
					"Left": "354",
					"Top": "453",
					"Height": "473",
					"Width": "473"
				},
				"FaceAttributes": {
					"Facetype": "Face",
					"Respirator": "Wear",
					"Blur": "0.1419367790222168",
					"Glasses": "None",
					"AppearanceScore": "",
					"Facequal": "60",
					"Integrity": "70",
					"Smiling": {
						"Value": "97",
						"Threshold": "95"
					},
					"Headpose": {
						"PitchAngle": "-1.5683923959732056",
						"RollAngle": "7.163370132446289",
						"YawAngle": "-6.925303936004639"
					}
				}
			}]
		}
	},
	"Message": "success",
	"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
	"Code": "200",
	"Success": "true"
}

错误码

HttpCode 错误码 错误信息 描述
400 ParameterIsNull The parameter must not be empty. 参数不能为空。
401 InvalidParameter The specified parameter is invalid. 非法参数。
403 NoPermission This RAM user has no permissions to access API. 该RAM用户无权访问API。
410 NoSubscribeService OSS is not activated or you have not granted OSS the read write permission. 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
412 InDebt You have an outstanding payment. Please add funds first and try again. 实人认证存在欠费,请充值后再进行操作。
421 ResourcesTooLarge The size of the incoming resources are too large. 传入资源超过了最大限制。
422 DownloadTimedOut Downloading resource timed out. 下载资源超时(3秒)。
435 NoFaceDetected No face is detected in either the image or the video. 图片或者视频中检测不到人脸信息。
500 SystemError A system error occurred. 系统内部错误。

访问错误中心查看更多错误码。