快速开始
集成 / SDK
用户验证
企业验证
交易监控
更新日志概述
人脸比对报告记录了活体检测期间采集的自拍照与参考图像（通常是从证件中提取的人像）之间的 1:1 生物特征比对。它返回一个介于 0 到 100 之间的相似度分数、两张被比对图像的签名 URL、参考图像的来源会话，以及比对过程中产生的任何警告。 该报告在用户完成工作流中的活体检测步骤和证件步骤之后生成（或者，对于基于肖像的工作流（如生物识别认证），仅在活体检测之后生成），或者在您自行提供两张任意人脸图像时直接通过独立的 Face Match API 生成。 每份报告都有其自己的status（独立于整体会话状态），该状态反映了仅人脸比对这一步骤的处理结果：
- Approved —
score高于审核阈值，且未触发自动拒绝警告。 - In Review —
score介于拒绝和审核阈值之间，或无法计算分数且face_match_not_computed_action为REVIEW。 - Declined —
score等于或低于拒绝阈值，触发了NO_REFERENCE_IMAGE，或无法计算分数且face_match_not_computed_action为DECLINE。 - Resub Requested — 审核员已从控制台请求用户重新提交此步骤。
- Not Finished — 人脸比对步骤尚未产生结果（包括用户正在重试失败采集的情况）。
在 API 响应中的位置
人脸比对报告包含在face_matches[] 数组中 — 始终为 JSON 数组，绝不是单个 face_match 对象。在至少一个人脸比对步骤生成数据之前，它为 null；当工作流运行人脸比对超过一次时，会出现多个条目。Adaptive Age Verification 工作流在运行身份证件验证回退时也会填充该数组：该条目将其 node_id 报告为年龄估算节点，因为该工作流自身没有人脸比对节点。
- 会话决策 API —
GET /v3/session/{sessionId}/decision/在顶层返回face_matches[]。请参阅检索会话决策。 - Webhooks — 一旦步骤生成数据，
session.status.updatedpayload 就会包含相同的face_matches[]数组。请参阅 Webhooks。 - 独立 Face Match API — 有关直接 1:1 比对的信息，请参阅独立 Face Match API。
读取
response.face_matches[0] 并遍历该数组 — 某些旧教程中引用的单个 face_match 结构在 v3 决策 endpoint 上并不存在。架构
规范的字段级架构位于数据模型参考页面。以下字段与该规范架构一致。状态值
在状态最终确定之前，低相似度失败会被重试：用户最多可以尝试采集
face_match_max_attempts 次（默认为 3 次），并且仅应用最后一次尝试的分数。在工作流节点上配置的自定义状态规则可以进一步调整最终状态，并按照 Declined > In Review > Approved 的优先级与基于分数的衍生状态相结合。
示例
Approved — 明确匹配
In Review — 临界相似度
Declined — 没有可供比对的参考图像
安全提示
source_image 和 target_image 的签名 URL 属于生物特征数据，在较短的有效期后即会过期。请将它们视为短期有效：切勿对其进行缓存或公开展示。通常，您的应用只需使用 status 和 score — 尽量减少存储，以减少服务器上的生物特征数据保留。
相关内容
- 人脸比对警告 — 完整警告枚举、成因及修复建议。
- 活体检测报告 — 采集目标图像的上游步骤。
- Webhook — 监听
session.status.updated以接收报告。 - 数据模型 — 人脸比对 — 包含所有字段的规范架构。