全部产品
Search

搜索本产品

    ID Verification：FACE_COMPARE

    文档中心

    ID Verification：FACE_COMPARE

    更新时间：Jan 14, 2026

    本文介绍通过纯服务端（API）接入FaceCompare的方案。

    接口说明

    • 接口名：FaceCompare

    • 请求方法：HTTPS POST

    • 接口说明：通过服务端接口传入图片资料等信息进行人脸比对。

    • QPS限量：API独享QPS限量，详情请参见ID Verification服务端API QPS限量说明。

    • 服务地址：

      说明

      • 内网访问优势：内网指阿里云同一地域内各产品间的私有通信网络。若您的业务服务器部署于阿里云对应地域，请使用内网域名访问 ID Verification 服务，以获得更安全、稳定的通信质量。 

      • 海外访问优化建议：海外网络环境复杂，建议参考服务端网络耗时分析与优化，优化集成方案，降低网络延迟及请求失败概率。

      中国香港

      • 公网：cloudauth-intl.cn-hongkong.aliyuncs.com

      • 内网：cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      印度尼西亚

      • 公网：cloudauth-intl.ap-southeast-5.aliyuncs.com

      • 内网：cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

    在线调试和集成

    说明

    在调试和集成前，请确保您已完整阅读使用OpenAPI调试和集成服务端API文档，充分了解API接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。

    您可以在OpenAPI Explorer中直接运行本接口进行调试，并生成本接口的SDK代码示例。

    传入图片格式要求

    • 图片格式：JPG、JPEG、PNG。

    • 图片大小：推荐50~100 KB，最大不超过1 MB。

    • 图片分辨率：不超过1920*1080（高*宽），至少为640*480（高*宽），推荐短边缩放到720像素，压缩率大于0.9。照片高大于宽，如果传入的照片宽大于高，可能会影响检测效果。

      说明

      图片转base64格式后，通常会导致数据体积增加。如您需要使用base64格式传参，请保证原始图片的体积不超过0.6MB，以满足1MB的最大数据传输限制。

    • 图片质量建议：

      • 人脸面部需要完整清晰无遮挡，正对摄像头，推荐通过前置摄像头采集的人脸图片。

      • 人脸大小占比图片中面积需要>60%，若人脸较小会影响检测的准确性。

      • 若图片中存在多个人脸，算法默认截取较大的人脸，建议避免传入多人脸图片。

    请求参数

    名称

    类型

    是否必选

    描述

    示例值

    MerchantBizId

    String

    是

    自定义的业务唯一标识，用于后续定位排查问题使用。支持长度为32位的字母和数字的组合，请确保唯一。

    e0c34a77f5ac40a5aa5e6ed20c35****

    SourceFacePicture

    String

    是

    人像照片Base64编码。

    说明

    如果您选择该方式传入证件图片，请检查照片大小，不要传入过大的照片。

    base64编码

    SourceFacePictureUrl

    String

    否

    人像图片地址，公网可访问的HTTP、HTTPS链接。

    说明

    SourceFacePicture与SourceFacePictureUrl二选一。

    https://***

    TargetFacePicture

    String

    否

    底库照片Base64编码。

    说明

    如果您选择该方式传入证件图片，请检查照片大小，不要传入过大的照片。

    base64编码

    TargetFacePictureUrl

    String

    否

    底库人像图片地址，公网可访问的HTTP、HTTPS链接。

    说明

    TargetFacePicture与TargetFacePictureUrl二选一。

    https://***

    返回数据

    名称

    类型

    描述

    示例值

    HTTP Status Code

    Integer

    HTTP状态码。

    200

    HTTP Body

    RequestId

    String

    请求ID。

    130A2C10-B9EE-4D84-88E3-5384FF0****

    Code

    String

    返回Code。

    Success

    Message

    String

    返回Code的详细描述。

    success

    Result.TransactionId

    String

    认证请求的唯一标识。

    08573be80f944d95ac812e019e36****

    Result.Passed

    String

    认证最终结果，取值：

    • Y：通过

    • N：不通过

    Y

    Result.FaceComparisonScore

    String

    人脸比对分：取值范围0～100。

    52.57

    返回Code

    HTTP Status Code

    Code

    描述

    200

    Success

    请求成功。

    400

    MissingParameter

    参数不能为空。

    400

    InvalidParameter

    非法参数。

    401

    NoFaceDetected

    自定义比对源的图片人脸特征提取失败，建议更换图片上传。

    401

    UnqualifiedPhoto

    传入的图片不可读，或图片分辨率不符合要求，建议更换图片。需确保照片清晰、曝光正常，完整无遮挡，角度无太大偏差。

    401

    ToolargeImage

    图片尺寸过大，建议压缩图片或更换图片上传方式。

    401

    DataDuplication

    同时通过Base64方式与链接方式传入图片。

    401

    DownloadTimeout

    URL图片下载超时。

    403

    Forbidden.RAMUserAccessDenied

    需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。更多信息，请参见授权RAM用户访问服务。

    403

    Forbidden.AccountAccessDenied

    确保您开通了ID verification，并且保证账户未欠费。

    403

    Throttling.Api

    API限流拦截。

    500

    InternalError

    系统内部错误，请反馈工程师排查。