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

# 活体检测报告：置信度分数、检测方法与人脸比对

> 了解 Didit 活体检测报告：涵盖状态、置信度分数、检测方法、年龄估算、跨会话人脸比对以及在 API 响应中的具体呈现位置。

## 概述

**活体检测报告**记录了 Didit 在验证摄像头前是否有真人（而非打印照片、屏幕回放或深度伪造）时观察到的一切信息。它包括活体检测方法、0–100 的置信度分数、参考自拍照和采集视频、可选的年龄估算、被动活体质量指标，以及与您应用的历史记录和黑名单进行跨会话人脸比对的结果。

该报告在用户完成工作流中的活体检测步骤（或调用独立人脸 endpoint）后生成。Didit 会运行三种活体检测方法之一（主动 3D、闪烁或被动），对捕获内容进行评分，排查已知的欺骗攻击模式，并在生物特征层面将该人脸与您应用中出现过的所有人脸进行比对。

每份报告都有其独立的 `status`（独立于整体会话状态），反映活体检测步骤本身的判定结果：

* **已通过** — 检测到人脸，活体检测分数高于审核阈值，未触发自动拒绝警告。
* **审核中** — 触发了一个或多个转入审核的警告，或者分数处于或低于审核阈值但高于拒绝阈值。
* **已拒绝** — 触发了自动拒绝条件（`NO_FACE_DETECTED`、`LIVENESS_FACE_ATTACK`、`FACE_IN_BLOCKLIST` 或年龄估算流程中的年龄风险），可配置的警告被路由为拒绝，或者分数处于或低于拒绝阈值。
* **未完成** — 用户未完成活体检测步骤。

## 在 API 响应中的位置

活体检测报告在 `GET /v3/session/{sessionId}/decision/` 中以 `liveness_checks[]` 形式呈现 — **始终为 JSON 数组**，绝不是单一的 `liveness` 对象。当工作流多次运行活体检测时（例如主要检查加上重新采集），会出现多个条目。

* **会话决策 API** — `GET /v3/session/{sessionId}/decision/` 在顶层返回 `liveness_checks[]`。参见[检索会话决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。
* **Webhook** — 一旦该步骤生成数据，`session.status.updated` payload 就会包含相同的 `liveness_checks[]` 数组。参见 [Webhook](https://docs.didit.me/zh/integration/webhooks.md)。
* **独立活体检测 API** — 参见[活体检测独立 API](https://docs.didit.me/zh/standalone-apis/passive-liveness.md)。

> [!NOTE]
>
> 请读取 `response.liveness_checks[0]` 并遍历该数组 — 某些旧教程中提到的单一 `liveness` 结构在 v3 决策 endpoint 上并不存在。

## 架构

标准的逐字段架构位于 [Data models](https://docs.didit.me/zh/reference/data-models.md#活体检测) 参考页面。以下字段与该标准架构保持一致。

| 字段 | 类型 | 说明 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | 活体检测步骤状态（见下文）。 |
| `node_id` | string \| null | 生成此报告的工作流图谱节点。 |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | 生成此采集结果的活体检测方式。 |
| `score` | number 0–100 \| null | 活体置信度分数，四舍五入保留 2 位小数。 |
| `reference_image` | string (签名 URL) \| null | 从采集结果中提取的参考自拍照。具有有限有效期的签名 URL。 |
| `video_url` | string (签名 URL) \| null | 完整的活体采集视频（主动方式）。具有有限有效期的签名 URL。 |
| `age_estimation` | number \| null | 参考图像中最大人脸的估算年龄（周岁）。 |
| `face_quality` | number 0–100 \| null | 被动活体检测人脸质量，归一化为百分比。仅在 `method = "PASSIVE"` 时填充。 |
| `face_luminance` | number 0–100 \| null | 被动活体检测面部亮度，从 0–255 归一化为百分比。仅在 `method = "PASSIVE"` 时填充。 |
| `matches[]` | array | 跨会话人脸匹配结果（见下文）。 |
| `warnings[]` | array | 模块级警告，参见 [Liveness warnings](https://docs.didit.me/zh/core-technology/liveness/warnings-liveness.md)。每个条目遵循 [Warning object](https://docs.didit.me/zh/reference/data-models.md#警告对象) 结构（`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`）。 |

### 跨会话人脸匹配

`matches[]` 列出了您应用历史记录中与此自拍照的生物特征相似度超过阈值的人脸（最多 5 个条目，黑名单和白名单人脸优先，然后按相似度降序排列）。符合条件的候选对象包括黑名单人脸、白名单人脸、来自 `Approved` 会话的人脸以及针对您的供应商用户导入的人脸。属于同一用户的人脸（相同的 `vendor_data`，或在可用时属于同一供应商用户）将被排除在**整个**搜索范围之外，包括重复人脸检测和黑名单筛查。

每个条目包含：

| 字段 | 类型 | 说明 |
| - | - | - |
| `session_id` | string (UUID) \| null | 匹配的会话。当 `source` 为 `imported` 或 `list_entry` 时为 `null`。 |
| `session_number` | number \| null | 匹配会话的顺序编号。对于非会话来源为 `null`。 |
| `similarity_percentage` | number 0–100 | 生物特征相似度分数，限制在 0–100 之间。 |
| `vendor_data` | string \| null | 来自匹配会话的您的参考数据（对于导入的人脸，则为供应商用户的参考数据）。 |
| `verification_date` | string (ISO 8601) \| null | 匹配会话（或导入人脸）的创建时间。 |
| `user_details` | object \| null | 来自匹配会话 KYC 的 `{ full_name, document_type, document_number }`。导入的人脸仅填充 `full_name`（两个证件字段为 `null`）；未记录详细信息时为 `null`。 |
| `match_image_url` | string (签名 URL) \| null | 来自匹配会话、导入人脸或名单条目的参考人脸。 |
| `status` | string \| null | 匹配会话的状态（例如 `"Approved"`）。对于非会话来源为 `null`。 |
| `is_blocklisted` | boolean | 当匹配的人脸位于您的人脸黑名单中时为 `true`。 |
| `is_allowlisted` | boolean | 当匹配的人脸位于您的人脸白名单中时为 `true`（跳过重复人脸操作）。 |
| `api_service` | string \| null | 当匹配人脸来自独立 API 调用（例如 `"PASSIVE_LIVENESS"`）时设置；对于工作流会话和非会话来源为 `null`。 |
| `source` | `"session" \| "imported" \| "list_entry"` | 匹配人脸的来源：另一个验证会话、针对供应商用户上传的人脸，或组织管理的白名单/黑名单人脸。 |

## 状态值

状态来自共享的功能状态枚举（`FeatureStatusChoices`）。

| 状态 | 含义 | 下游影响 |
| - | - | - |
| `Approved` | 检测到人脸，活体检测分数高于审核阈值，未触发自动拒绝警告。 | 计为成功的活体检测。 |
| `In Review` | 分数处于或低于审核阈值但高于拒绝阈值，或触发了路由至审核的警告。 | 会话也会转为 `In Review`，直到审核员执行操作。 |
| `Declined` | 触发了自动拒绝风险（`NO_FACE_DETECTED`、`LIVENESS_FACE_ATTACK`、`FACE_IN_BLOCKLIST`，或年龄估算流程中的年龄风险），某个可配置警告被路由至拒绝，或分数处于或低于拒绝阈值。 | 除非另一个已通过的分支满足工作流条件，否则会话将被拒绝。 |
| `Not Finished` | 用户放弃了活体检测步骤（或可重试的采集失败正在等待下一次尝试）。 | 活体检测分支未生成结果。 |
| `Resub Requested` | 审核员从控制台请求重新提交此步骤。 | 临时状态；用户重新采集后即被替换。 |

## 示例

### Approved: 正常的主动 3D 采集

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review: 被动活体检测，低质量采集并存在疑似重复

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

此处人脸质量（12.4）低于默认审核阈值（15），亮度（18.7）低于默认最低值（20），且工作流的重复人脸操作设置为 Review，因此所有三个警告均带有 `log_type: "warning"`，报告结果为 `In Review`。

## 安全提示

活体检测视频和自拍照属于生物识别数据，签名 URL 为临时链接并且会过期（默认 4 小时后）。请将其视为短效数据：不要对其进行缓存或公开展示。通常您的应用仅需要 `status`、`score` 和警告信息，应尽可能少地存储生物识别数据，以最大程度减少服务器上的生物识别数据。

## 相关内容

* [活体检测警告](https://docs.didit.me/zh/core-technology/liveness/warnings-liveness.md) — 完整的警告枚举、原因及处置措施。
* [Webhook](https://docs.didit.me/zh/integration/webhooks.md) — 监听 `session.status.updated` 以接收报告。
* [数据模型 — 活体检测](https://docs.didit.me/zh/reference/data-models.md#活体检测) — 包含所有字段的标准模式。
* [人脸比对报告](https://docs.didit.me/zh/core-technology/face-match/report-face-match.md) — 与证件人像比对的配套 1:1 人脸比对。


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