全部产品
Search

搜索本产品

    ID Verification：FACE_LIVENESS_MIN_PRO

    文档中心

    ID Verification：FACE_LIVENESS_MIN_PRO

    更新时间：Jul 13, 2026

    FACE_LIVENESS_MIN_PRO是一项通过API接口调用的真实人脸检测服务。该服务接收预先获取的人脸图像作为输入，并依托Qwen-VL大模型深度分析伪造风险，以精准判定是否为真人。鉴于App或Web SDK模式具备更高的安全性，若您的业务对真实人脸核验的安全等级要求较高，建议集成这两种模式。

    接口说明

    • 接口名：FaceLivenessV2

    • 请求方法：HTTPS POST

    • 接口说明：调用FaceLivenessV2接口对人脸图片进行活体检测。

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

    • 服务地址：

      说明

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

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

      新加坡

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

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

      印度尼西亚

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

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

      中国香港

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

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

      马来西亚（吉隆坡）

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

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

    在线调试和集成

    说明

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

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

    传入人脸图片格式要求

    • 人像图片传入提供三种方式，任选其一即可。

      • Base64模式：FacePictureBase64

      • URL模式：FacePictureUrl

      • 文件流模式：FacePictureFile

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

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

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

      说明

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

    • 图片质量建议：

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

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

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

    请求参数

    名称

    类型

    是否必选

    描述

    示例值

    ProductCode

    String

    是

    接入的产品方案。取值FACE_LIVENESS_MIN_PRO

    FACE_LIVENESS_MIN_PRO

    MerchantBizId

    String

    是

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

    说明

    阿里云服务器不会对该字段的值进行唯一性检查。为了更好地跟踪，强烈建议保证字段唯一性。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MerchantUserId

    String

    是

    自定义的用户ID，或者其他可以识别特定用户的标识，例如：手机号码、邮箱地址等。强烈建议对该字段的值进行预先脱敏，例如对值进行哈希处理。

    123456789

    FacePictureBase64

    String

    否

    照片Base64编码。如果您选择FacePictureBase64（照片Base64编码）方式传入人脸照片，请注意检查照片大小，不要传入过大的照片。

    base64

    FacePictureUrl

    String

    否

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

    https://***

    FacePictureFile

    InputStream

    否

    人像地址，文件流传输。

    人像图⽚的InputStream对象

    FaceQualityCheck

    String

    否

    人脸质量检查功能，默认不开启，取值：

    • N：不开启。

    • Y：开启。

    开启后，系统将自动拦截模糊、遮挡等低质量的人脸照片，阻止其进入后续比对等环节。建议在对识别精度要求较高或需减少无效请求的场景下开启。拦截返回401（UnqualifiedPhoto）。

    N

    FaceAttributeCheck

    String

    否

    是否需要返回额外的人脸属性字段。

    • N：关闭（默认）。

    • Y：开启，在ExtFaceInfo的faceAttributeInfo字段中以字符串形式返回。

    N

    返回数据

    名称

    类型

    描述

    示例值

    HTTP Status Code

    Integer

    HTTP状态码。

    200

    HTTP Body

    RequestId

    String

    请求ID。

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

    Result.TransactionId

    String

    整个认证流程的唯一标识。

    hksb7ba1b28130d24e015d694361****

    Code

    String

    返回Code，具体信息请参见服务端返回HTTP状态码说明。

    Success

    Message

    String

    返回Code的详细描述。

    Success

    Result.Passed

    String

    认证结果，取值：

    • Y：通过

    • N：不通过

    Y

    Result.SubCode

    String

    认证结果描述。更多信息，请参见ResultObject.SubCode错误码说明。

    200

    Result.ExtFaceInfo

    Object

    静默活体检测相关结果信息。关于JSON格式，请参见右侧示例。更多信息，请参见ExtFaceInfo。

    {
  "FaceQualityScore": 76.69,
  "OcclusionResult": "N",
  "FaceAttack": "Y",
  "SharpnessScore": 60.78,
  "KaOcclusionScore": 100,
  "FaceGender": "M",
  "OcclusionScore": 99.99,
  "FaceAge": 28,
  "IlluminationScore": 97.43
}

    ResultObject.SubCode错误码说明

    错误码

    是否计费

    描述和原因建议

    200

    是

    认证通过。

    205

    是

    活体检测存在风险。

    ExtFaceInfo

    名称

    类型

    描述

    示例值

    FaceQualityScore

    Double

    活体人脸质量分数。取值范围0～100，数值越大质量越高。

    88.62

    OcclusionScore

    Double

    质量判断子维度，遮挡的算法分数，取值范围0～100，数值越大质量越高。

    99.99

    KaOcclusionScore

    Double

    质量判断子维度，关键区域遮挡的算法分数，取值范围0～100，数值越大质量越高。

    100

    IlluminationScore

    Double

    质量判断子维度，光照的算法分数，取值范围0～100，数值越大质量越高。

    97.43

    SharpnessScore

    Double

    质量判断子维度，图片清晰度分数，取值范围0～100，数值越大质量越高。

    60.78

    FaceAttack

    String

    采集人脸是否涉及活体攻击。

    • Y：涉及攻击。

    • N：不涉及攻击。

    N

    FaceAttributeInfo

    String

    检测传入图片中的主体人脸（离镜头最近、面部面积最大且清晰的人脸）的相关面部属性。检测结果以字符串形式返回，据此决策消费内容。

    返回字段定义如下：

    • gender：主体人物性别。1 代表男性，0 代表女性。

    • glasses：主体人物是否携带眼镜。1 代表检测到对应信息，0 代表未检测到。

    • hat：主体人物是否头顶戴帽子（包含头巾/头纱场景）。1 代表检测到对应信息，0 代表未检测到。

    • mask：主体人物是否戴口罩。1 代表检测到对应信息，0 代表未检测到。

    • tattoo：主体人物是否有可见纹身。1 代表检测到对应信息，0 代表未检测到。

    • smoking：主体人物是否在抽烟。1 代表检测到对应信息，0 代表未检测到。

    • others：除主体外是否还有其他人物出现。1 代表检测到对应信息，0 代表未检测到。

    • env：主体人物所在的环境，例如办公室、工厂、医院、车内等。目前支持返回 office / hospital / factory / vehical / other。

    • expression：主体人物是否为夸张表情（指人物面部出现明显异于自然/平静状态的强烈表情）。1 代表检测到夸张表情，0 代表未检测到。

    • age：主体人物对应的真实年龄（周岁）。对应真实年龄。

    {
        gender: 1
        glasses: 0
        hat: 1
        mask: 1
        tattoo: 0
        smoking: 0
        others: 1
        env：office
        expression：1
        age：16
}