ID Verification：FACE_IDU_MIN

名称

类型

是否必选

描述

示例值

ProductCode

String

是

产品方案标识，固定取值：FACE_IDU_MIN。

FACE_IDU_MIN

MerchantBizId

String

是

商户业务唯一标识，用于后续定位排查问题。支持32 位字母和数字组合。服务端不校验此ID唯一性，商户应自行保证唯一。

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

是

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

123456789

SourceFacePicture

String

三种上传方式任选其一，用于传入活体检测的人像图片。

【API方案传入人脸图像】人像图片 Base64 编码。

base64

SourceFacePictureUrl

String

【API方案传入人脸图像】人像图片地址，公网可访问的 HTTP、HTTPS 链接。

https://***face1.jpeg

SourceFacePictureFile

String

【API方案传入人脸图像】人像图片文件流

具体接入方式，请参见特殊场景：文件上传 Advance 接口配置。

FaceQualityCheck

String

否

N

FaceAttributeCheck

String

否

N

VerifyModel

String

是

【产品方案配置】核验模式：

• 1验证模式：1:1核验（默认）

• 0检索模式：1:N检索

• 2综合模式：1:1核验+1:N检索

0

TargetFacePicture

String

VerifyModel=1或2时必选，三种上传方式任选其一。

【产品方案配置-1:1核验】1:1 比对的可信目标人脸照片Base64编码。

base64

TargetFacePictureUrl

String

【产品方案配置-1:1核验】人像图片地址，公网可访问的HTTP、HTTPS链接。

https://***face2.jpeg

TargetFacePictureFile

String

【产品方案配置-1:1核验】人像图片文件流。

具体接入方式，请参见特殊场景：文件上传 Advance 接口配置。

FaceGroupCodes

String

VerifyModel=0或2时必选

【产品方案配置-1:N检索】1:N 检索的人脸库编码。通过ID Verification产品控制台创建人脸库时获取对应编码，最大支持同时查询10个人脸库。当传入多个人脸库编码时，以逗号区分。

sg*****xta，s*****uk3j

ReturnFaces

String

VerifyModel=0或2时必选

【产品方案配置-1:N检索】多张人脸超过匹配阈值时返回的匹配人脸数量，默认返回1，最大支持5。

1

AutoRegistration

String

VerifyModel=0或2时必选

【产品方案配置-1:N检索】认证通过后是否自动注册至人脸库：

• 0：自动注册

• 1：不注册（默认）

0

FaceRegisterGroupCode

String

VerifyModel=0或2，且AutoRegistration=0时必选

【产品方案配置-1:N检索】自动注册入库的目标人脸库编码。

sg*****xta

UpdateFaceIfUserExists

String

VerifyModel=0或2时必选

【产品方案配置-1:N检索】自动注册入库时若 MerchantUserId 已存在，是否使用本次人脸覆盖原有人脸：

• Y：覆盖

• N：不覆盖（默认），并返回 UserId 已存在

N

核验模式

VerifyModel 值

核心逻辑

适用场景

关键输入参数

触发自动注册入库条件

验证模式（默认）

1

活体检测 + 1:1 核验

登录、账号找回、敏感操作确认

TargetFacePicture、TargetFacePictureUrl或 TargetFacePictureFile（三选一传入目标人脸）

不适用

检索模式

0

活体检测 + 1:N 检索

新用户注册防重、一人一号管控

FaceGroupCodes（指定检索人脸库）；
ReturnFaces（可选，配置匹配阈值以上的返回人脸数量）

活体检测通过，且 1:N 检索未命中

综合模式

2

活体检测 + 1:1 核验 + 1:N 检索

新增用户注册（需同时确认本人身份并查重）

需同时传入验证模式（值为 1）与检索模式（值为 0）所需的全部关键参数

活体检测通过、1:1 核验通过，且 1:N 检索未命中

名称

类型

描述

示例值

HTTP Status Code

Integer

HTTP状态码。

200

HTTP Body

RequestId

String

请求ID。

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

Code

String

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

Success

Message

String

返回Code的详细描述。

success

Result.TransactionId

String

认证请求的唯一标识。

4ab0b***cbde97

Result.SubCode

String

认证结果描述。请参考Result.SubCode认证结果子码说明。

200

Result.FacePassed

String

认证最终结果，取值：

• Y：通过

• N：不通过

Y

Result.FaceAttack

String

是否检测到活体攻击：

• Y：是

• N：否

N

Result.FaceAttributeInfo

String

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

Result.ExtFaceInfo

Object

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

{
  "FaceQualityScore": 66.3,
  "OcclusionScore": 100,
  "SharpnessScore": 70.3,
  "KaOcclusionScore": 80,
  "IlluminationScore": 90.79
}

Result.FaceComparisonScore

Double

【VerifyModel=1/2时返回】人脸比对结果，比对分范围 0~100；系统默认阈值为 90，也可以基于自身业务需求自定义决策。

98

Result.DuplicateFace

String

【VerifyModel=0/2时返回】重复人脸检索结果；检索到相似人脸时返回。

返回字段定义如下：

• faceGroupCode：相似人脸的人脸库编码

• faceId：相似人脸的人脸 ID

• merchantUserId：相似人脸的用户唯一ID

• score：相似人脸的分数

[
  {
    "faceGroupCode": "sg7****uzt",
    "faceId": "f5a921*******9e792ec84c8f0ca592a"
    "merchantUserId":"face0005",
    "score":93.26
  }
]

Result.FaceRegistrationResult

Integer

【VerifyModel=0/2时返回】人脸库注册结果：

• 0：注册失败，人脸图片原因导致

• 1：注册成功

• 2：注册失败，自动注册入库条件未满足

• 3：注册失败，用户已存在

• 4：注册成功，人脸图片更新成功（符合自动注册入库条件，但MerchantUserId重复，且UpdateFaceIfUserExists=Y）

1

Result.FaceRegistrationId

String

【VerifyModel=0/2且AutoRegistration=0 并注册成功时返回】人脸注册ID。

9e792******a592a

名称

类型

描述

示例值

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

错误码

认证记录是否计费

描述和原因建议

200

是

认证通过。

204

是

【1:1验证结果】人脸比对不一致，可能不是同一人或活体照片质量较低。

205

是

【活体攻击】活体检测存在风险。

233

是

【1:N检索结果】检测到相似人脸。应结合 Result.ExtFaceInfo.duplicateFace 信息处理重复注册或身份冒用风险。