> ## 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 如何将人脸生物识别信息关联到供应商 User 实体，包括 1:N 人脸搜索、重复检测、人脸黑名单执行和手动上传。



人脸生物识别提示
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

粘贴到

人脸生物识别是每个用户实体的核心。Didit 在[活体检测](https://docs.didit.me/zh/core-technology/liveness/overview.md)期间采集人脸，生成向量嵌入，并将其存储，用于四项后续功能：**1:N 人脸搜索**、**重复检测**、**黑名单拦截**和**生物识别再认证**。> [!NOTE]
>
> 已存储的人脸还可作为[生物识别认证](https://docs.didit.me/zh/core-technology/biometric-auth/overview.md)的参考：使用用户的 `vendor_data` 创建生物识别认证会话并省略 `portrait_image`，Didit 将自动复用已存储的人脸（依次优先使用：已通过的活体检测人脸、电子护照芯片照片、证件人像，最后是手动录入的用户资料人脸）。## 人脸如何关联到用户**1. 在活体检测期间采集**当用户进入启用了活体检测的会话时，Didit 会采集自拍照，运行被动活体检测，提取最大的人脸，并生成用于搜索的向量嵌入。**2. 存储到用户资料**人脸会关联到该会话及其所属的用户实体。人像 URL 会以 `portrait_image` 的形式显示在用户资料中。**3. 建立搜索索引**该嵌入会被添加到搜索索引中。之后的会话可以针对此索引运行 1:N 搜索。## 人脸搜索 (1:N)人脸搜索允许您上传一张图片，并将其与应用中所有已录入的人脸进行比对，从而找到对应的用户。使用场景：- **注册时的重复检测**：防止同一人创建两个账户。
- **反向查找**：在欺诈调查中，通过 CCTV 画面或图片识别对应的用户。
- **回头客识别**：为回头客跳过 KYC。当您的工作流启用了重复检测时，人脸搜索会在新会话期间自动运行。它也以独立 API 的形式提供：- `POST /v3/face-search/`：[独立人脸搜索](https://docs.didit.me/zh/standalone-apis/face-search.md)## 重复检测每张新的人脸都可以与已录入的人脸进行比对，以发现重复项。Didit 会为每张人脸分配一个 `approved_duplicate_status`：| 状态 | 含义 |
| - | - |
| `NOT_DUPLICATED` | 未找到相似度阈值以上的匹配项 |
| `DUPLICATED` | 人脸与一个或多个已通过会话中的人脸匹配 |可以将工作流配置为：- **拒绝**被标记为重复的会话。
- **标记待审核**：转交人工分析师处理。
- **仅警告**：允许通过，但添加风险标签。请在控制台的 *工作流 → \[您的工作流] → 人脸比对 / 活体检测 → 重复检测* 中进行配置。## 人脸黑名单拒绝会话不会将人脸添加到任何黑名单中。若要拒绝之后使用同一张人脸的会话，您需要自行将其加入黑名单：可以在[黑名单页面](https://docs.didit.me/zh/console/blocklist-users.md)中添加，也可以使用[名单 API](https://docs.didit.me/zh/management-api/lists/overview.md)。之后，若新会话的活体自拍与该条目匹配，则会被自动拒绝。## 将导入的人脸上传到用户资料如果您正在从其他 KYC 服务商迁移，可以先创建用户，然后将可信的人脸图片附加到该用户资料上。用户仍然以您的 `vendor_data` 作为标识，但人脸上传接口使用 Didit 内部的用户 ID（`didit_internal_id`），以确保目标用户明确无误。**1. 创建或获取用户**使用您稳定的 `vendor_data` 调用 [`POST /v3/users/create/`](https://docs.didit.me/zh/management-api/users/create)；如果用户已存在，则调用 `GET /v3/users/{vendor_data}/`。**2. 读取 didit\_internal\_id**用户响应中包含 `didit_internal_id`。在您自己的系统中继续使用 `vendor_data`；`didit_internal_id` 仅用于用户资料附加接口。**3. 上传人脸**使用 base64 编码的人脸图片调用 [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/zh/management-api/users/upload-face)。```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```导入的用户资料人脸会被录入到用于重复检测和人脸搜索的同一人脸索引中。它们不会被自动加入黑名单。若要拦截已知的不良行为者，请改为将人脸上传到人脸类型的名单中。> [!WARNING]
>
> 仅上传您根据自身隐私声明和迁移协议有权处理的人脸。只有在可以安全地向合规运营人员展示时，才在 `metadata` 或 `comment` 中保留来源服务商的标识符。### 黑名单的添加方式| 触发条件 | 操作 |
| - | - |
| 会话状态为 `DECLINED` | 不会添加到任何黑名单；用户保持 `ACTIVE` |
| 分析师在控制台中手动将人脸加入黑名单 | 添加人脸，并根据策略更新用户状态 |
| 通过名单 API 以编程方式添加 | 将人脸图片上传到人脸类型的黑名单 |### 将人脸上传到黑名单若要以编程方式通过人脸拦截用户，请使用专用的[上传人脸到名单](https://docs.didit.me/zh/management-api/lists/upload-face.md)接口，将人脸图片上传到人脸类型的黑名单。Didit 会提取生物特征嵌入，并将其插入对应的索引中。此后，任何活体自拍与之匹配的会话都会被自动拒绝。> [!NOTE]
>
> 用户资料人脸上传与人脸黑名单上传是两种不同的操作。使用用户资料上传，可以将可信的导入人脸附加到用户上，用作证据、用于重复检测和人脸搜索。使用[名单 API](https://docs.didit.me/zh/management-api/lists/overview.md)拦截人脸，可使之后匹配的会话被拒绝。### 从黑名单中移除人脸在控制台的 *黑名单 → 人脸 → 行操作 → 移除* 中删除该条目，或使用[删除条目](https://docs.didit.me/zh/management-api/lists/delete-entry.md)接口。## 会话删除后保留的生物特征模板删除会话会删除人脸图像，默认情况下还会删除人脸特征向量，因此该用户不再参与重复检测和人脸搜索。如果您在审核通过后很快删除会话，但仍需识别重复注册，请在应用中启用[生物特征模板保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)，或在删除请求中发送 `retain_face_embeddings: true`。Didit 会照常删除该会话及其所有数据，并保留一个由 Didit 单独管理、不含图像的人脸生物特征模板，该模板关联到用户：- 它仅包含数值化的人脸模板和保留元数据。它绝不包含人脸图像、活体视频、证件数据、提取的身份字段、决策结果，也不包含已删除会话的 ID。
- 它与在线会话中的人脸一样，参与重复检测、人脸搜索、生物识别认证以及您的人脸名单。命中结果会以 `source: "retained_template"`、用户的 `vendor_user_id` 和 `vendor_data`，以及 `biometric_template_id` 返回。
- 它属于生物识别数据，并带有有限期限，由 `expires_at` 指定。在以下任一情况下会被清除：删除该用户、使用 `deletion_instruction: "privacy_erasure"` 删除该用户的任一会话、模板到期，或您在 **Lists → 生物特征模板** 中手动清除，或通过[生物特征模板 API](https://docs.didit.me/zh/management-api/biometric-templates/overview.md) 清除。
- 未包含 `vendor_data` 的会话没有可关联模板的用户。删除此类会话时会报告 `ineligible_no_vendor_user`，人脸特征向量会随会话一并删除。
- 保留的模板绝不会被加入黑名单。从已删除会话创建的人脸黑名单条目会保留其自身独立的生物识别条目及生命周期。关联到用户的模板会显示在用户资料的 **生物特征模板** 下，并提供清除操作。## 人脸生命周期摘要```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## 从控制台上传人脸具有合规权限的操作人员可以手动上传人脸：1) 进入 *Users → \[user] → Actions → Upload face*。
2) 选择图像，Didit 会提取最大的人脸，并存储一条与该用户关联的新人脸记录。
3) 该人脸将作为用户资料证据，并用于重复检测和人脸搜索。如需拒绝未来的匹配会话，请使用黑名单区域。此功能适用于以下情况：- 您已通过线下渠道核验某位客户，并持有其已知肖像。
- 您希望使用欺诈数据库中已知的恶意行为者预先填充黑名单。## 隐私与保留- 人脸特征向量是数值向量，而不是图像。图像本身存储在加密对象存储中，并通过签名 URL 访问。人脸特征向量属于生物识别数据。
- 保留期限遵循您应用的[数据保留](https://docs.didit.me/zh/console/data-retention.md)政策。被保留的生物特征模板则遵循更严格且有期限的[生物特征模板保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)期限。
- 删除会话会删除图像，默认还会删除特征向量。如果您的应用已选择启用生物特征模板保留，删除会话时会保留一个不含图像的模板，直至其到期或被清除。
- 对于 GDPR / CCPA 的被遗忘权请求，请使用 `deletion_instruction: "privacy_erasure"` 删除该人员的会话，或删除用户。两种方式都会同时清除所有保留的模板。您管理的人脸黑名单条目会一直保留，直至您将其移除。## 后续步骤> [card] [人脸搜索](https://docs.didit.me/zh/core-technology/face-search/overview.md)
>
> 1:N 人脸搜索的工作原理。> [card] [活体检测](https://docs.didit.me/zh/core-technology/liveness/overview.md)
>
> 捕获人脸的活体检测。> [card] [黑名单 API](https://docs.didit.me/zh/management-api/lists/upload-face.md)
>
> 将人脸上传到黑名单。> [card] [生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md)
>
> 会话删除后保留的模板。> [card] [用户黑名单](https://docs.didit.me/zh/entities/users/blocklist.md)
>
> 用户加入黑名单的工作原理。


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