全部产品
阿里云办公

人脸比对验证

更新时间:2018-09-12 14:46:06

描述

接口名称CompareFaces

功能描述: 指定两张人脸图片进行比对,输出两张图片中人脸的相似度分值作为结果。

功能限制

  • 指定的比对图片中至少应含有一个图片类型是人脸照FacePic
  • 一张图片中含有多个人脸时,算法会自动选取图片中占幅最大的人脸。
  • 两张比对的图片中,如果其中一张检测不到人脸,系统会返回未检测到人脸的错误提示。

名词解释

  • 图片类型: 指的是进行比对图片的类型说明,具体有以下两种:
    • FacePic: 用户人脸照。
    • IDPic: 用户二代身份证芯片中的头像照,通常由二代身份证阅读仪设备读取并解码获得。
  • 图片地址格式: 用来告诉人脸验证服务如何获取到图片,图片地址描述有以下几种模式:

    • 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,
  • 人脸相似度SimilarityScore: 用来描述两个图片中人脸的相似程度,取值范围为[0, 100],值越大相似度越高。

  • 误识率: 将其他人误识别为指定人员的概率。

请求参数

名称 类型 是否必须 描述
Action String 系统规定参数。取值: CompareFaces
RegionId String 系统规定参数。取值: cn-hangzhou
SourceImageType String 图片 1 的类型,参看名词图片类型
SourceImageValue String 图片 1 的地址,参看名词图片地址格式
TargetImageType String 图片 2 的类型,参看名词图片类型
TargetImageValue String 图片 2 的地址,参看名词图片地址格式

返回参数

名称 类型 是否必须 描述
SimilarityScore Float 参看名词人脸相似度
ConfidenceThresholds String 人脸比对置信度阈值,返回内容是 JSON Object。其中,key是误识率,value是对应的阈值。

错误码说明

错误代码 英文描述 中文描述 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. 参数错误,请检查参数是否为空。 403
Error.NoPermissionAccess No permission to access our service. 没有权限访问服务,请确认是否服务已开通。 403
Error.CompareFacesError CompareFaces action failed due to internal error. 人脸比对过程中出现内部未知错误,请联系技术支持排查。 500
InvalidParam.ImageTypeEmpty The image type is empty. SourceImageType 或者 TargetImageType 字段为空。 400
InvalidParam.FacePicNotGiven At least one of the two given images has a type of FacePic. 进行比对的两个图片中,至少其中一个图片的类型应该设置为人脸照FacePic 400
InvalidParam.ImageValuePatternError The pattern of value of given image is not acceptable. 图片地址格式错误,请检查 ImageValue 是否符合图片地址格式的要求。 400
InvalidParam.ImageTypeInvalid The image type is not valid. SourceImageType / TargetImageType 取值不为 FacePic 或者 IDPic 400
Error.NoFaceDetected No face detected from given images. 指定图片中没有检测到人脸。 400

示例

使用 SDK 开发包示例

参看 SDK 开发包使用文档中的人脸验证示例:JavaPHPPython.NETNode.jsGo

拼接 HTTPS 请求示例

请求示例

  1. https://cloudauth.aliyuncs.com/?Action=CompareFaces
  2. &RegionId=cn-hangzhou
  3. &SourceImageType=FacePic
  4. &SourceImageValue=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg
  5. &TargetImageType=IDPic
  6. &TargetImageValue=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg
  7. &<公共请求参数>

返回示例

XML 格式:

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <CompareFacesResponse>
  3. <Data>
  4. <ConfidenceThresholds>{"0.0001":"90.07","0.001":"80.02","0.01":"70.01"}</ConfidenceThresholds>
  5. <SimilarityScore>0.9825757</SimilarityScore>
  6. </Data>
  7. <Success>true</Success>
  8. <Code>1</Code>
  9. </CompareFacesResponse>

JSON 格式:

  1. {
  2. "Code": "1",
  3. "Data": {
  4. "ConfidenceThresholds": "{\"0.0001\":\"90.07\",\"0.001\":\"80.01\",\"0.01\":\"70.02\"}",
  5. "SimilarityScore": 98.7913
  6. },
  7. "Success": true
  8. }

示例中,人脸比对置信度阈值confidenceThresholds值的说明:

  • “0.0001”: “90.07” 表示误识率为 0.01% 时的对应阈值为 90.07。
  • “0.001”: “80.01” 表示误识率为 0.1% 时的对应阈值为 80.01。
  • “0.01”: “70.02” 表示误识率为 1% 时的对应阈值为 70.02。

注意: 置信度阈值会根据不同图像和算法动态给出,请不要将置信度阈值持久化。