调用CompareFaces进行人脸比对。

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

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

  • 一张图片中含有多个人脸时，算法会自动选取图片中占幅最大的人脸。
  • 两张比对的图片中，如果其中一张检测不到人脸，系统会返回“未检测到人脸”的错误提示。

在传入图片时，您需要上传图片对应的HTTP地址或Base64编码。

  • HTTP地址：可访问的公网HTTP地址。例如，http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg。
  • Base64编码：图片的Base64编码字符串。例如，/9j/4AAQSkZJRgABAQAAAQABAAD/xxx。

图片限制

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

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

调试

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

请求参数

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

要执行的操作。取值：CompareFaces。
BizId String 是 39ecf51e-2f81-4dc5-90ee-ff86125be683

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

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

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

SourceImageBase64 String 是 /9j/4AAQSkZJRgABAQAAAQABAAD/xxx

上传图片1对应的Base64编码（不需要以base64开头）。

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

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

说明 SourceImageUrl和SourceImageBase64二选一。
TargetImageBase64 String 是 /9j/4AAQSkZJRgABAQAAAQABAAD/xxx

上传图片2对应的Base64编码（不需要以base64开头）。

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

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

说明 TargetImageUrl和TargetImageBase64二选一。

返回数据

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

HTTP状态码。
Message String success

请求信息的响应消息。
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

本次请求的ID。
ResultObject Struct

结果信息。
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。

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

两个图片中人脸的相似程度。取值范围为0~100，值越大表示相似度越高。
Success Boolean true

是否成功响应。取值：

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

示例

请求示例

http(s)://[Endpoint]/?Action=CompareFaces
&BizId=39ecf51e-2f81-4dc5-90ee-ff86125be683
&BizType=RPBasicTest
&SourceImageBase64=/9j/4AAQSkZJRgABAQAAAQABAAD/xxx
&SourceImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
&TargetImageBase64=/9j/4AAQSkZJRgABAQAAAQABAAD/xxx
&TargetImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
&<公共请求参数>

正常返回示例

XML格式 

<CompareFacesResponse>
         <ResultObject>
                 <ConfidenceThresholds>{"0.0001":"90.07","0.001":"80.01","0.01":"70.02"}</ConfidenceThresholds>
                 <SimilarityScore>98.7913</SimilarityScore>
         </ResultObject>
         <Message>Error.InternalError</Message>
         <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
         <Code>200</Code>
</CompareFacesResponse>

JSON格式 

{
	"ResultObject": {
		"ConfidenceThresholds": "{\"0.0001\":\"90.07\",\"0.001\":\"80.01\",\"0.01\":\"70.02\"}",
		"SimilarityScore": "98.7913"
	},
	"Message": "Error.InternalError",
	"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
	"Code": "200"
}

错误码

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. 系统内部错误。

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