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

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

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

上传图片地址的说明:在传入图片时,您需要上传其对应的HTTP/OSS地址或base64编码。

  • HTTP地址:可访问的公网HTTP地址。例如,http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
  • base64编码:通过base64编码的图片,格式为base64://<图片 base64 字符串>

图片限制:

  • 不支持本地图片的相对路径或绝对路径。
  • 单张图片大小请控制在2M内,避免算法拉取超时。
  • 单个请求的Body有8M的大小限制,请计算好请求中所有图片和其他信息的大小,不要超限。
  • 使用base64传递图片时,接口的请求方法需要改成 POST;图片base64字符串需要去掉头部描述,如data:image/png;base64,

调试

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

请求参数

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

要执行的操作。取值:DetectFaceAttributes

ClientTag String test

照片标签,默认值为null,表示默认不带标签。

说明 长度不超过5个字节。
DontSaveDB Boolean true

照片是否入库,默认值为true,表示照片默认入库。

MaterialValue String http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg

待检测照片,格式描述见上传图片地址的说明。

MaxFaceNum Integer 1

最多检测多少张人脸。默认值为1,最大值为5

MaxNumPhotosPerCategory Integer 1

如果照片需要入库,相同 ClientTag 保留的最大张数,新的照片会替换最老的。默认值为1,最大值为4

RetAttributes String gender,headpose,blur,glasses,age,facetype

指定需要检测的内容,检测内容越多接口耗时越大。取值:

  • facetype:是否人脸
  • headpose:人脸姿态
  • glasses:是否戴眼镜
  • blur:是否模糊
  • smiling:是否笑脸
  • gender:性别
  • age:年龄

返回数据

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

HTTP状态码。

Data Struct

返回数据。

FaceInfos Array

人脸检测结果。

FaceAttributesDetectInfo
FaceAttributes Struct

人脸属性。

Age Integer 2

年龄。

Blur Float 0.1419367790222168

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

Ethnicity String Asian

种族。取值:

  • Asian:亚洲人
  • White:欧洲人
  • Black:非洲人
Facetype String Face

是否人脸,取值:

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

性别。

Score Float 0.7767378687858582

性别置信度,分值越大越可信。通常以 Value 值为准即可。

Value String Female

性别,取值:

  • Female:女性
  • Male:男性
Glasses String None

是否戴眼镜,取值:

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

人脸姿态。

PitchAngle Float -1.5683923959732056

抬头角度,单位为度。

RollAngle Float 7.163370132446289

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

YawAngle Float -6.925303936004639

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

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

原图宽度,单位为像素。

Message String Error.InternalError

错误代码。

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

本次请求的ID。

Success Boolean true

是否成功响应。

示例

请求示例

https://cloudauth.aliyuncs.com/?Action=DetectFaceAttributes
&RegionId=cn-hangzhou
&<公共请求参数>

请求body
MaterialValue=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg
&RetAttributes=gender%2cheadpose%2cblur%2cglasses%2cage%2cfacetype
&MaxFaceNum=1
&DontSaveDB=true
&ClientTag=
&MaxNumPhotosPerCategory=1

正常返回示例

XML 格式

<DetectFaceAttributesResponse>
     <Code>200</Code>
     <Data>
          <FaceInfos>
               <FaceAttributesDetectInfo>
                    <element>
                         <FaceAttributes>
                              <Age>2</Age>
                              <Blur>0.14193678</Blur>
                              <Ethnicity>Asian</Ethnicity>
                              <Facetype>Face</Facetype>
                              <Gender>
                                   <Score>0.77673787</Score>
                                   <Value>Female</Value>
                              </Gender>
                              <Glasses>None</Glasses>
                              <Headpose>
                                   <PitchAngle>-1.5683924</PitchAngle>
                                   <RollAngle>7.16337</RollAngle>
                                   <YawAngle>-6.925304</YawAngle>
                              </Headpose>
                              <Smiling></Smiling>
                         </FaceAttributes>
                         <FaceRect>
                              <Height>473</Height>
                              <Left>354</Left>
                              <Top>453</Top>
                              <Width>473</Width>
                         </FaceRect>
                    </element>
               </FaceAttributesDetectInfo>
          </FaceInfos>
          <ImgHeight>1920</ImgHeight>
          <ImgWidth>1080</ImgWidth>
     </Data>
     <Success>true</Success>
</DetectFaceAttributesResponse>

JSON 格式

{
    "Data": {
        "ImgWidth": 1080,
        "ImgHeight": 1920,
        "FaceInfos": {
            "FaceAttributesDetectInfo": [
                {
                    "FaceAttributes": {
                        "Facetype": "Face",
                        "Headpose": {
                            "PitchAngle": -1.5683923959732056,
                            "RollAngle": 7.163370132446289,
                            "YawAngle": -6.925303936004639
                        },
                        "Glasses": "None",
                        "Blur": 0.1419367790222168,
                        "Ethnicity":"Asian",
                        "Smiling": {},
                        "Gender": {
                            "Score": 0.7767378687858582,
                            "Value": "Female"
                        },
                        "Age": 2
                    },
                    "FaceRect": {
                        "Left": 354,
                        "Top": 453,
                        "Height": 473,
                        "Width": 473
                    }
                }
            ]
        }
    },
    "Code": "200",
    "Success": true
}

错误码

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