调用CompareFaces进行人脸比对。

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

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

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

在传入图片时,您需要上传图片对应的HTTP地址或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 CompareFaces

要执行的操作。取值:CompareFaces

TargetImageType String FacePic

图片2的类型,取值:

  • FacePic: 用户人脸照
  • IDPic: 用户二代身份证芯片中的头像照(通常由二代身份证阅读仪设备读取并解码获得)
SourceImageType String FacePic

图片1的类型,取值:

  • FacePic: 用户人脸照
  • IDPic: 用户二代身份证芯片中的头像照(通常由二代身份证阅读仪设备读取并解码获得)
SourceImageValue String http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg

图片1的地址。具体请参见关于上传图片地址的说明。

TargetImageValue String http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg

图片2的地址。具体请参见关于上传图片地址的说明。

返回数据

名称 类型 示例值 描述
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

本次请求的ID。

Success Boolean true

是否成功响应。

Code String 200

HTTP状态码。

Message String Error.InternalError

错误代码。

Data Struct

人脸比对结果。

SimilarityScore Float 98.7913

两个图片中人脸的相似程度。取值范围为[0, 100],值越大相似度越高。

ConfidenceThresholds String {"0.0001":"90.07","0.001":"80.01","0.01":"70.02"}

人脸比对置信度阈值。返回内容是JSON Object,具体结构为"key":"value"

  • key是误识率,即将其他人误识别为指定人员的概率。
  • value是对应的阈值。
说明 关于示例中的人脸比对置信度阈值(confidenceThresholds):
  • "0.0001": "90.07"表示误识率为0.01%时的对应阈值为90.07。
  • "0.001": "80.01"表示误识率为0.1%时的对应阈值为80.01。
  • "0.01": "70.02"表示误识率为1%时的对应阈值为70.02。

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

示例

请求示例

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

请求body
SourceImageType=FacePic
&SourceImageValue=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg
&TargetImageType=IDPic
&TargetImageValue=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg

正常返回示例

XML 格式

<CompareFacesResponse>
      <Data>
            <ConfidenceThresholds>{"0.0001":"90.07","0.001":"80.01","0.01":"70.02"}</ConfidenceThresholds>
            <SimilarityScore>98.7913</SimilarityScore>
      </Data>
      <Success>true</Success>
      <Code>200</Code>
</CompareFacesResponse>

JSON 格式

{
  "Code": "200",
  "Data": {
    "ConfidenceThresholds": "{\"0.0001\":\"90.07\",\"0.001\":\"80.01\",\"0.01\":\"70.02\"}",
    "SimilarityScore": 98.7913
  },
  "Success": true
}

错误码

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