字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

商户侧的业务唯一标识。建议与业务订单、申请单或流水号一一对应，以便追踪业务。

说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。

"VV2026060500000001"

metaInfo

String

512

是

-

SDK与用户设备的元信息。原生App模式下该值由ZOLOZ SDK返回，请直接传入，不要进行任何修改。

"{\"apdidToken\":\"xxx\",\"appName\":\"com.example.app\",\"appVersion\":\"1.0.0\",\"bioMetaInfo\":\"3.46.0:0,2\",\"deviceModel\":\"iPhone13,3\",\"deviceType\":\"ios\",\"osVersion\":\"iOS 26.1\"}"

userId

String

64

条件必填

-

商户侧用户标识。checkFaceConsistency 未传或为 N 时必填；为 Y 时，userId 与 faceContent 必须且只能传一个。选择 userId 方式时，须使用同商户下已有注册底图对应的 userId（例如 Connect enroll 时使用的 userId），不可使用任意新用户标识。此时系统将使用该底图进行人脸一致性校验。未开启人脸一致性时，userId 仅作为用户标识使用。

"enrolled_user_001"

sceneCode

String

64

否

null

业务场景码，用于区分不同业务场景的数据表现，例如login、riskVerify、payment、changePassword。

"changePassword"

productConfig

ProductConfig

-

否

null

VideoVerify产品的精细化配置参数。具体可配置项，详见ProductConfig。

{

"riskMode": "STANDARD",

"deeperMode": "STANDARD"

}

checkFaceConsistency

String

1

否

N

是否开启人脸一致性校验：Y 开启，N 关闭。为 Y 时，userId 与 faceContent 必须且只能传一个。该字段在请求顶层，与 productConfig 同级；商户需先开通对应能力。

"Y"

faceContent

FaceContent

-

条件必填

null

商户传入的比对底图。checkFaceConsistency=Y 且未传 userId 时必填；不可同时传 userId。结构见下方 FaceContent。

{"content":"BASE64_IMAGE_DATA","sourceOfFace2":"SELFIE"}

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

riskMode

String

10

否

STANDARD

VideoVerify中的多维度风控冷却规则校验，用于拦截可疑交易。取值：

• CLOSED：关闭风控冷却规则。该等级适用于测试场景，测试进程不受风控规则的影响。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

"STANDARD"

deeperMode

String

10

否

CLOSED

AIGC攻击检测的Deeper等级，Deeper检测功能的详细介绍，请参见什么是Deeper。该参数支持以下取值：

• CLOSED：Deeper的所有能力均不开启，例如AIGC检测算法、终端风险检测等。如果业务场景不需要AIGC攻击检测，则无需开启。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

注意：需要先购买Deeper产品，才能使用该功能。

"CLOSED"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

content

String

-

是

-

标准 Base64 编码的图片数据，不带 data URI 前缀。支持 JPG/JPEG、PNG、BMP。解码后的底图不得超过 5 MB；底图与 SDK 采集的 Pano 主图解码后的总大小也不得超过 5 MB。

"BASE64_IMAGE_DATA"

rect

String

-

否

null

可选的人脸区域，单位为像素，格式为“左、上、宽、高”，英文逗号分隔。左、上为非负整数，宽、高为正整数，不能超出上传图片边界。不传时由算法检测人脸。不要直接传“左、上、右、下”坐标。

"100,80,200,200"

sourceOfFace2

String

-

否

按 SELFIE 处理

底图来源：SELFIE 表示自拍/人脸照片；对应证件 docType 表示证件脸图片；00000001007 表示 ZOLOZ 暂不支持的证件中的人脸图片。未传或为空时按 SELFIE 处理。

"SELFIE"

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API请求结果，包含结果状态、结果码和结果消息。

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

transactionId

String

否

ZOLOZ服务器为本次流程生成的交易ID。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

• 请求参数非法，例如入参格式错误或缺失必传参数。
• 请求未能成功到达服务器，例如网络问题或网关故障。
• 系统限流导致请求被拒绝。

"G006600016CN2019011400000000957252****"

clientCfg

String

否

客户端配置，包括SDK连接和行为参数。仅当result.resultStatus为S时返回。

"..."

结果码

结果状态

描述

SUCCESS

S

API调用成功。

HIGH_RISK

F

检测到高风险，用户账号被风控冻结。

DEVICE_NOT_SUPPORT

F

当前设备类型不支持。

OS_NOT_SUPPORT

F

当前操作系统不支持。

SDKVERSION_NOT_SUPPORT

F

当前SDK版本不支持。

INVALID_ARGUMENT

F

输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。

SYSTEM_ERROR

F

系统内部错误。有关错误详情，请查看返回的resultMessage。

UNABLE_GET_IMAGE

F

faceContent 图片为空、损坏或格式不支持。Base64 非法、底图超限或 rect 非法，返回 INVALID_ARGUMENT。