传入照片格式要求

当您在进行人脸比对的时候,请传入满足以下所有条件的2张人脸照片。

  • 近期照片/底库近期照片,人脸完整清晰无遮挡,表情自然,正对摄像头。
  • 照片清晰、曝光正常,脸部无过黑、过亮、光晕等情况、角度无太大偏差。
  • 分辨率不超过1920*1080(高*宽),至少640*480,推荐短边缩放到720像素,压缩率大于0.9。照片高大于宽,如果传入的照片宽大于高,可能会影响检测效果。
  • 照片大小:<1MB。
  • 支持 90、180 和270度照片,多人脸的情况会选取最大脸。
示例如下:示例照片

发起认证请求

说明
  • 接口名:CompareFaceVerify。
  • 服务地址:cloudauth.aliyuncs.com。
  • 请求方法:HTTPS POST和GET。
  • 接口说明:通过服务端接入实现实人认证的接口。
  1. 入参字段
    名称 类型 是否必须 描述 示例值
    SceneId Long 认证场景ID。 1000000006
    OuterOrderNo String 商户请求的唯一标识。

    值为32位长度的字母数字组合前面几位字符是商户自定义的简称,中间可以使用一段时间,后段可以使用一个随机或递增序列。

    e0c34a77f5ac40a5aa5e6ed20c353888
    ProductCode String 固定值:PV_FC。 PV_FC
    SourceFaceContrastPicture String 必填,在四种传入人脸照片方式中,选择一种:
    • FaceContrastPicture
    • FaceContrastPictureUrl
    • CertifyId
    • OSS
    照片Base64编码。 /9j/4AAQSkZJRgABAQAASxxxxxxx
    SourceFaceContrastPictureUrl String OSS照片地址,目前只支持已授权OSS照片地址。 https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg
    SourceCertifyId String 之前实人认证通过的CertifyId,认证时的照片作为人脸比对照片。 0bfa7c493f850e5178b9f8613634c9xx
    SourceOssBucketName String 已授权OSS空间的 Bucket 名。 cn-shanghai-aliyun-cloudauth-xxxxx
    SourceOssObjectName String 已授权OSS空间的文件名。 verify/xxxxx/xxxxxx.jpeg
    TargetFaceContrastPicture String 必填,在四种传入底库人脸照片方式中,选择一种:
    • FaceContrastPicture
    • FaceContrastPictureUrl
    • CertifyId
    • OSS
    底库照片Base64编码。 /9j/4AAQSkZJRgABAQAASxxxxxxx
    TargetFaceContrastPictureUrl String 底库OSS照片地址,目前只支持已授权OSS照片地址。 https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg
    TargetCertifyId String 之前实人认证通过的 CertifyId,认证时的照片作为人脸比对照片。 0bfa7c493f850e5178b9f8613634c9xx
    TargetOssBucketName String 已授权OSS空间的Bucket名 。 cn-shanghai-aliyun-cloudauth-xxxxx
    TargetOssObjectName String 已授权OSS空间的文件名。 verify/xxxxx/xxxxxx.jpeg
    说明

    以Source开头的参数代表您要上传的近期人脸照片参数,以Target开头的参数代表您要上传的底库近期人脸照片参数。传入照片格式要求请参见 传入照片格式要求

    如果您选择OSS方式传入人脸照片,您必须同时传入OssBucketName和OssObjectName字段。

    OSS入参格式仅支持开通实人认证时授权的OSS生成的URL、Bucket和文件名 。关于如何查询授权的OSS,请参见 开通OSS空间并授权

    如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。

  2. 返回字段
    名称 类型 是否必须 描述 示例值
    RequestId String 请求 ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
    Message String 错误信息。 success
    Code String 返回码:200为成功,其他为失败。 200
    ResultObject.Passed String 是否通过,通过为T,不通过为F。 T
    ResultObject.VerifyScore Float 人脸比对分。 99.60875

    返回值示例

    {
        "Code": "200",
        "Message": "success",
        "RequestId": "23699272-B263-4B6C-BC04-0EBA1AB6F6D5",
        "ResultObject": {
            "Passed": "T",
            "VerifyScore": 99.60875
        }
    }
  3. 返回Code、Message说明
    Code Message 描述
    200 success 成功。
    400 参数不能为空 参数不能为空。
    401 参数非法 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
    402 应用配置不存在 应用配置不存在。
    404 认证场景配置不存在 认证场景配置不存在,请先在控制台上创建认证场景。
    410 未开通服务 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
    411 RAM 无权限 需要给子账号授予AliyunAntCloudAuthFullAccess的操作权限。
    412 欠费中 金融级实人认证或OSS存在欠费,请充值后操作。
    419 传入图片不可用 图片无法下载、图片内容为空、图片分辨率不符合要求或提取不到人脸特征,建议更换图片。
    420 数据重复 图片传入方式超过2种。
    • FaceContrastPicture
    • FaceContrastPictureUrl
    • Oss
    • CertifyId
    421 传入图片过大 图片超过了1 MB,建议压缩图片或更换图片上传方式。
    422 下载图片超时 图片下载超过了3秒,请排查网络后重新操作。
    423 状态错误 传入的certifyID认证状态需要为T,您也可以更换其他方式传入图片。
    500 系统错误 系统内部错误,请联系工程师排查。

SDK 使用说明

说明

如需其他语言的SDK示例代码,您可以通过OpenAPI Explorer在线调试工具调试API接口。该工具会自动生成SDK示例代码。

Java SDK使用示例

  • Maven依赖
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>4.4.3</version>
    </dependency>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-cloudauth</artifactId>
        <version>2.0.11</version>
    </dependency>
  • 使用示例(JSON)
    DefaultProfile profile = DefaultProfile.getProfile(
      "cn-hangzhou",    // 固定cn-hangzhou
      "AccessKeyID",      // 您的Access Key ID
      "AccessKeySecret");  // 您的Access Key Secret
    IAcsClient client = new DefaultAcsClient(profile);
    
    CompareFaceVerifyRequest request = new CompareFaceVerifyRequest();
    request.setSceneId(10xxxxxxL);
    request.setOuterOrderNo("商户请求的唯一标识");
    // 固定值
    request.setProductCode("PV_FC");
    
    // 请在以下四种传入人脸照片方式中,选择一种
    // 1.照片Base64编码
    // 2.照片OSS bucket名和文件名
    // 3.照片OSS的URL地址
    // 4.已经实人认证通过的CertifyId
    
    // 方式一:照片Base64
    request.setSourceFaceContrastPicture("人脸照片Base64编码");
    // 方式二:照片OSS bucket名和文件名
    //request.setSourceOssBucketName("cn-shanghai-aliyun-cloudauth-xxxxx");
    //request.setSourceOssObjectName("verify/xxxxx/xxxxxx.jpeg");
    // 方式三:照片OSS的URL地址,公网可访问
    //request.setSourceFaceContrastPictureUrl("https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg")
    // 方式四:已经实人认证通过的CertifyId
    //request.setSourceCertifyId("0bfa7c493f850e5178b9f8613634c9xx");
    
    // 请在以下四种传入底库人脸照片方式中,选择一种
    // 1.照片Base64编码
    // 2.照片OSS bucket名和文件名
    // 3.照片OSS的URL地址
    // 4.已经实人认证通过的CertifyId
    
    // 方式一:照片Base64
    request.setTargetFaceContrastPicture("底库人脸照片Base64编码");
    // 方式二:照片OSS bucket名和文件名
    //request.setTargetOssBucketName("cn-shanghai-aliyun-cloudauth-xxxxx");
    //request.setTargetOssObjectName("verify/xxxxx/xxxxxx.jpeg");
    // 方式三:照片OSS的URL地址,公网可访问
    //request.setTargetFaceContrastPictureUrl("https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg")
    // 方式四:已经实人认证通过的CertifyId
    //request.setTargetCertifyId("0bfa7c493f850e5178b9f8613634c9xx");
    
    CompareFaceVerifyResponse response = client.getAcsResponse(request);
    System.out.println(response.getCode());
    System.out.println(response.getMessage());
    System.out.println(response.getRequestId());
    System.out.println(response.getResultObject().getPassed());
    System.out.println(response.getResultObject().getVerifyScore());