> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 人脸比对报告：相似度分数与 JSON 响应结构

> 解读 Didit 1:1 人脸比对报告：包含状态、相似度分数、源/目标图片 URL、警告，以及在 API 响应中的数据字段位置。

## 概述

**人脸比对报告**记录了活体检测期间采集的自拍照与参考图像（通常是从证件中提取的人像）之间的 1:1 生物特征比对。它返回一个介于 0 到 100 之间的相似度分数、两张被比对图像的签名 URL、参考图像的来源会话，以及比对过程中产生的任何警告。

该报告在用户完成工作流中的活体检测步骤和证件步骤之后生成（或者，对于基于肖像的工作流（如生物识别认证），仅在活体检测之后生成），或者在您自行提供两张任意人脸图像时直接通过独立的 [Face Match API](https://docs.didit.me/zh/standalone-apis/face-match.md) 生成。

每份报告都有其自己的 `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](https://docs.didit.me/zh/core-technology/age-estimation/overview.md#自适应年龄估算) 工作流在运行身份证件验证回退时也会填充该数组：该条目将其 `node_id` 报告为年龄估算节点，因为该工作流自身没有人脸比对节点。

* **会话决策 API** — `GET /v3/session/{sessionId}/decision/` 在顶层返回 `face_matches[]`。请参阅[检索会话决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。
* **Webhooks** — 一旦步骤生成数据，`session.status.updated` payload 就会包含相同的 `face_matches[]` 数组。请参阅 [Webhooks](https://docs.didit.me/zh/integration/webhooks.md)。
* **独立 Face Match API** — 有关直接 1:1 比对的信息，请参阅[独立 Face Match API](https://docs.didit.me/zh/standalone-apis/face-match.md)。

> [!NOTE]
>
> 读取 `response.face_matches[0]` 并遍历该数组 — 某些旧教程中引用的单个 `face_match` 结构在 v3 决策 endpoint 上并不存在。

## 架构

规范的字段级架构位于[数据模型](https://docs.didit.me/zh/reference/data-models.md#人脸比对)参考页面。以下字段与该规范架构一致。

| 字段 | 类型 | 说明 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | 人脸比对步骤状态（`FeatureStatusChoices`）。 |
| `node_id` | string \| null | 生成此报告的工作流图谱节点。 |
| `score` | number 0–100 \| null | 生物特征相似度分数，保留 2 位小数。无法进行比对时为 `null`。 |
| `source_image_session_id` | string \| null | 其存储的肖像提供了参考（源）图像的会话 UUID — 在基于肖像的流程（生物识别认证，或在会话创建时提供的肖像）中设置。当参考图像是在同一会话中采集的证件肖像时为 `null`。 |
| `source_image` | string (signed URL) | 参考图像（通常为证件肖像）。短时有效的签名 URL — 请及时下载，切勿持久化存储该 URL。 |
| `target_image` | string (signed URL) | 目标图像（通常为活体检测自拍照）。短时有效的签名 URL — 请及时下载，切勿持久化存储该 URL。 |
| `warnings[]` | array | 模块级警告。每个条目包含 `feature`（始终为 `"FACEMATCH"`）、`risk`、`additional_data`、`log_type`、`short_description`、`long_description` 和 `node_id` — 请参阅[人脸比对警告](https://docs.didit.me/zh/core-technology/face-match/warnings-face-match.md)。 |

## 状态值

| 状态 | 含义 | 下游影响 |
| - | - | - |
| `Approved` | 分数高于审核阈值，且未触发自动拒绝警告。 | 计为成功的人脸比对。 |
| `In Review` | 分数高于拒绝阈值但等于或低于审核阈值，或无法计算分数（`FACE_MATCH_NOT_COMPUTED`，例如在没有留下参考图像的非证件查询后），且 `face_match_not_computed_action` 设置为 `REVIEW`。 | 会话也会进入 `In Review` 状态，直至审核员执行操作。 |
| `Declined` | 分数等于或低于拒绝阈值，触发了 `NO_REFERENCE_IMAGE`，或无法计算分数且 `face_match_not_computed_action` 设置为 `DECLINE`。 | 会话被拒绝，除非另一个已通过的分支满足了工作流要求。 |
| `Resub Requested` | 审核员已从控制台请求重新提交此步骤。 | 要求用户重新采集。 |
| `Not Finished` | 人脸比对步骤未产生结果（缺少输入、工作流从未到达比对步骤，或用户仍处于采集重试循环中）。 | 该分支未完成。 |

在状态最终确定之前，低相似度失败会被重试：用户最多可以尝试采集 `face_match_max_attempts` 次（默认为 3 次），并且仅应用最后一次尝试的分数。在工作流节点上配置的自定义状态规则可以进一步调整最终状态，并按照 `Declined` > `In Review` > `Approved` 的优先级与基于分数的衍生状态相结合。

## 示例

### Approved — 明确匹配

```json theme={null}
{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}
```

### In Review — 临界相似度

```json theme={null}
{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

### Declined — 没有可供比对的参考图像

```json theme={null}
{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

## 安全提示

`source_image` 和 `target_image` 的签名 URL 属于生物特征数据，在较短的有效期后即会过期。请将它们视为短期有效：切勿对其进行缓存或公开展示。通常，您的应用只需使用 `status` 和 `score` — 尽量减少存储，以减少服务器上的生物特征数据保留。

## 相关内容

* [人脸比对警告](https://docs.didit.me/zh/core-technology/face-match/warnings-face-match.md) — 完整警告枚举、成因及修复建议。
* [活体检测报告](https://docs.didit.me/zh/core-technology/liveness/report-liveness.md) — 采集目标图像的上游步骤。
* [Webhook](https://docs.didit.me/zh/integration/webhooks.md) — 监听 `session.status.updated` 以接收报告。
* [数据模型 — 人脸比对](https://docs.didit.me/zh/reference/data-models.md#人脸比对) — 包含所有字段的规范架构。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.