全部产品
阿里云办公

人脸有效性检测

更新时间:2018-09-12 14:32:15

描述

接口名称DetectFaceAttributes

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

名词解释

  • 图片地址格式: 用来告诉人脸验证服务如何获取到图片,图片地址描述有以下几种模式:

    • http: 一个可访问的公网 HTTP 地址,例如 http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
    • oss: 一个可公开访问的 OSS 文件地址,格式为 oss://<bucket>:<path_to_file>
    • base64: 一个 base64 编码的图片,格式为 base64://<图片base64字符串>

      注意

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

    • Facetype:是否人脸。
    • Headpose:人脸姿态。
    • Glasses:是否戴眼镜。
    • Blur:是否模糊。
    • Smiling:是否笑脸。
    • Gender:性别。
    • Age:年龄。

请求参数

名称 类型 是否必须 描述
MaterialValue String 待检测照片,格式参看名词图片地址格式
RetAttributes String 需要检测的内容,参看名词检测内容
MaxFaceNum Integer 最多检测多少张人脸,默认传1
DontSaveDB Boolean 照片是否不入库,默认传true
ClientTag String 照片标签,默认传null。
MaxNumPhotosPerCategory Integer 如果照片需要入库,相同 ClientTag 保留的最大张数,新的照片会替换最老的,默认传1

返回参数

名称 类型 是否必须 描述
ImgWidth Integer 原图宽度,单位为像素。
ImgHeight Integer 原图高度,单位为像素。
FaceInfos Map 人脸检测结果。

FaceInfos 参数结构

名称 类型 是否必须 描述
FaceAttributesDetectInfo Map 人脸属性检测结果。

FaceAttributesDetectInfo 参数结构

名称 类型 是否必须 描述
FaceAttributes Map 人脸属性。
FaceRect Map 人脸在原图中的位置。

FaceAttributes 参数结构

名称 类型 是否必须 描述
Facetype String 是否人脸,None:不是人脸,Face:人脸,Profile:侧脸(左右转头超过30°)。
注意:若没有检测到脸,接口返回的 faceInfos 即为空;这里的None代表检测到脸,但认为是卡通或宠物等。
Headpose Map 人脸姿态。
Glasses String 是否戴眼镜,None:未戴眼镜,Wear:戴普通眼镜,Sunglass:戴墨镜。
Blur Float 人脸模糊度,分值越大越模糊。通常≥2.0已较模糊,建议根据实际业务数据测试调整。
Smiling Map 是否笑脸。
Gender Map 性别。
Age Integer 年龄。

Headpose 参数结构

名称 类型 是否必须 描述
PitchAngle Float 抬头角度,单位为弧度。
RollAngle Float 左右歪头角度,单位为弧度。
YawAngle Float 左右转头角度,单位为弧度。

Gender 参数结构

名称 类型 是否必须 描述
Value String 性别,Female为女性,Male为男性。
Score Float 性别置信度,分值越大越可信。通常以 Value 值为准即可。

Smiling 参数结构

名称 类型 是否必须 描述
Value Float 笑脸分值。
Threshold Float 笑脸阈值。

FaceRect 参数结构

名称 类型 是否必须 描述
Left Integer 人脸矩形左上角距原图左边的距离,单位为像素。
Top Integer 人脸矩形左上角距原图上边的距离,单位为像素。
Height Integer 人脸矩形的高度。
Width Integer 人脸矩形的宽度。

错误码说明

错误代码 英文描述 中文描述 HTTP 状态码
Error.InternalError The request processing has failed due to some unknown error. 服务内部出现未知错误,请联系技术支持排查。 500
InvalidParam.ParamMissing Please check if there is param empty in your imput. 参数错误,请检查参数是否为空。 400
Error.NoPermissionAccess No permission to access our service. 没有权限访问服务,请确认是否服务已开通。 403

示例

拼接 HTTPS 请求示例

请求示例

  1. https://cloudauth.aliyuncs.com/?Action=DetectFaceAttributes
  2. &RegionId=cn-hangzhou
  3. &MaterialValue=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg
  4. &RetAttributes=gender%2cheadpose%2cblur%2cglasses%2cage%2cfacetype
  5. &MaxFaceNum=1
  6. &DontSaveDB=true
  7. &ClientTag=
  8. &MaxNumPhotosPerCategory=1
  9. &<[公共请求参数]>

返回示例

JSON 格式:

  1. {
  2. "Data":{
  3. "ImgWidth":1080,
  4. "ImgHeight":1920,
  5. "FaceInfos":{
  6. "FaceAttributesDetectInfo":[
  7. {
  8. "FaceAttributes":{
  9. "Facetype":"Face",
  10. "Headpose":{
  11. "PitchAngle":-1.5683923959732056,
  12. "RollAngle":7.163370132446289,
  13. "YawAngle":-6.925303936004639
  14. },
  15. "Glasses":"None",
  16. "Blur":0.1419367790222168,
  17. "Smiling":{},
  18. "Gender":{
  19. "Score":0.7767378687858582,
  20. "Value":"Female"
  21. },
  22. "Age":2
  23. },
  24. "FaceRect":{
  25. "Left":354,
  26. "Top":453,
  27. "Height":473,
  28. "Width":473
  29. }
  30. }
  31. ]
  32. }
  33. },
  34. "Code":"1",
  35. "Success":true
  36. }