> ## 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 Schema

> 解析 Didit 生物识别认证响应，包含活体检测以及与已留存人像的可选人脸比对结果，通过 liveness_checks 和 face_matches 返回。

生物识别认证报告是 Didit 反馈回访用户重新验证结果的方式。该工作流会运行一次全新的活体检测；当工作流中启用人脸比对时，还会与创建会话时解析的参考人脸进行 1:1 人脸比对（即您提供的 `portrait_image`，或通过 `vendor_data` 查询到的用户已存储的人脸）。这两项检查均作为标准功能项出现在 V3 会话决策响应中。

![结合了活体检测以及与已存储肖像进行人脸比对的 Didit 生物识别认证报告](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/biometric-auth-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=c02e5558780972797d4b2feea685bc73)

## 概述

生物识别认证是一种工作流类型（`workflow_type: "biometric_authentication"`），而非单独的响应对象。工作流运行时会生成：

* 一次**活体检测**：采集实时自拍照并针对欺骗攻击进行评分。
* 一次**人脸比对**：将采集到的人脸与创建会话时解析的参考人脸进行比对（仅在工作流中启用人脸比对时）。

每当工作流包含人脸比对时，创建会话都需要一张参考人脸。您可以发送 `portrait_image`（Base64 编码的图像，最大 2MB），或者将其省略，此时 Didit 会复用已为该 `vendor_data` 用户存储的人脸：优先使用已通过的活体检测人脸，其次是电子护照（ePassport）芯片照片，再次是身份证件肖像，最后是手动录入的个人资料中的人脸。如果既没有 `portrait_image` 也没有已存储的人脸，创建会话将返回 `400` 并附带 `{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}`。在这两种情况下，解析出的参考都会记录在新会话下，因此人脸比对项的 `source_image_session_id` 会设置为该会话自身的 `session_id`（这表明参考来自该会话存储的肖像，而非在同一会话中采集的证件肖像，后者会使该字段为 `null`）。

## 出现位置

| 决策响应键 | 数量 | 项架构 |
| - | - | - |
| `liveness_checks[]` | 每个活体检测步骤对应一项（在生物识别认证中通常为 1） | [data-models#liveness-check](https://docs.didit.me/zh/reference/data-models.md#活体检测) |
| `face_matches[]` | 每个人脸比对步骤对应一项（在仅活体检测工作流中为 `null`） | [data-models#face-match](https://docs.didit.me/zh/reference/data-models.md#人脸比对) |

对于工作流类型为 `biometric_authentication` 的会话，这两个数组均由 [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/zh/sessions-api/retrieve-session) 返回。它们始终为数组形式（绝非单个对象），且在对应步骤生成数据之前均为 `null`。每个项都包含一个 `node_id`，以便多实例工作流消除步骤之间的歧义。

## 架构参考

完整字段列表已在数据模型页面统一定义，因此呈现这些功能的所有报告共享同一个权威来源：

* [活体检测项架构](https://docs.didit.me/zh/reference/data-models.md#活体检测) — `status`、`method`、`score`、`reference_image`、`video_url`、`age_estimation`、`matches[]`、`face_quality`、`face_luminance`、`warnings[]`、`node_id`。
* [人脸比对项架构](https://docs.didit.me/zh/reference/data-models.md#人脸比对) — `status`、`score`、`source_image_session_id`、`source_image`、`target_image`、`warnings[]`、`node_id`。
* [警告条目结构](https://docs.didit.me/zh/reference/data-models.md#警告对象) — `feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`。

## 状态值

`liveness_checks[].status` 和 `face_matches[].status` 均使用通用的功能生命周期（[功能级状态](https://docs.didit.me/zh/reference/data-models.md#功能级状态)）：

| 状态 | 含义 |
| - | - |
| `Not Finished` | 步骤尚未生成最终结果（用户未完成或已流失）。在步骤完全开始之前，其在决策响应中的数组直接为 `null`。 |
| `Approved` | 检查已通过所有配置的阈值。 |
| `In Review` | 评分落在审核区间内，或者某个可配置警告被设置为审核。 |
| `Declined` | 评分达到或低于拒绝阈值，或者触发了自动拒绝警告（人脸攻击、未检测到人脸、人脸在黑名单中、人脸比对无参考图像）。 |
| `Resub Requested` | 审核员要求用户重试此步骤。 |

会话整体的 `status` 汇总了这两个项：任何功能处于 `Declined` 都会使会话被拒绝；任何处于 `In Review` 都会使会话处于 `In Review`；否则为 `Approved`（在所有功能完成后）。

有关阈值行为和警告代码的完整列表，请参阅[生物识别认证警告](https://docs.didit.me/zh/core-technology/biometric-auth/warnings-biometric-authentication.md)。

## 示例 — 活体检测 + 人脸比对 (已通过)

示例已作删减：完整的决策外层数据还包含 `session_url`、`metadata`、`callback`、`reviews`、`contact_details`、`expected_details`、`environment`、`created_at` 和 `expires_at`。

```json theme={null}
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}
```

## 示例 — 仅活体检测 (工作流中已禁用人脸比对)

```json theme={null}
{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}
```

仅活体检测模式是一种工作流配置：当禁用人脸比对时，创建会话时无需参考人脸，且 `face_matches` 保持为 `null`。当启用人脸比对**时**，省略 `portrait_image` 并不会回退到仅活体检测：Didit 会复用为 `vendor_data` 用户存储的人脸，如果不存在存储的人脸，会话创建将失败并返回 `400`。

## 示例 — 因相似度低而拒绝人脸比对

```json theme={null}
{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "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"
        }
      ]
    }
  ]
}
```

## 安全注意事项

`reference_image`、`video_url`、`source_image` 和 `target_image` 是带有签名的 URL，在有限的有效期（默认为 4 小时）后会过期。它们指向生物识别数据——切勿对其进行缓存或公开展示。请在您方保存验证结果（状态、评分、`source_image_session_id`）；如果您需要新的 URL，请重新调用决策 endpoint。

## 相关内容

> [card] [生物识别认证警告](https://docs.didit.me/zh/core-technology/biometric-auth/warnings-biometric-authentication.md)
>
> 警告代码、阈值以及自动拒绝条件。

> [card] [活体检测报告](https://docs.didit.me/zh/core-technology/liveness/report-liveness.md)
>
> `liveness_checks[]` 项的完整字段参考。

> [card] [人脸比对报告](https://docs.didit.me/zh/core-technology/face-match/report-face-match.md)
>
> `face_matches[]` 项的完整字段参考。


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