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

# 人脸搜索 1:N API：检测重复账户与欺诈者

> Didit 人脸搜索可在所有已验证用户中检索人脸，快速识别重复账户和黑名单欺诈者。随 Didit 身份验证免费提供，响应时间低于 2 秒。

人脸搜索是一项强大的功能，允许您在所有已通过的身份证件验证会话中搜索特定人脸。该功能有助于识别重复账户、防范欺诈并增强您的安全措施。

人脸搜索集成提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

粘贴到

关于解读验证结果的 Academy 课程在 6:53 处讲到人脸搜索和黑名单。[人脸搜索和黑名单 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Didit 人脸搜索 1:N 流程，集成活体检测用于重复和黑名单检测](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## 自动人脸搜索集成> 在验证会话的活体检测过程中，系统会自动执行人脸搜索，以检测重复用户并比对黑名单人脸。### 自动重复检测当用户在身份验证过程中完成活体检测时：- 其面部生物特征会自动与所有先前已验证的用户进行比对
- 系统根据人脸相似度识别潜在的重复账户
- 系统会根据您配置的相似度阈值标记匹配项
- 您可以审核潜在的重复用户并采取相应操作### 黑名单集成人脸搜索可与[黑名单功能](https://docs.didit.me/zh/management-api/lists/overview.md)无缝集成：- 在验证过程中，人脸会自动与您的黑名单进行比对
- 如果发现与黑名单中的人脸匹配，验证将被自动拒绝
- 这可以防止先前识别出的问题用户创建新账户
- 有助于维护验证流程的完整性### 证件采集期间拍摄的自拍照当用户拍摄证件照片时，前置摄像头会拍摄其自拍照（静默采集）。每次评估证件时，该自拍照都会经历与活体自拍照相同的 1:N 搜索：- 它会与您的人脸黑名单以及应用中已通过验证的用户进行比对，采用与活体搜索相同的相似度阈值和优先级。
- 黑名单匹配会触发 `FRONT_CAMERA_FACE_IN_BLOCKLIST`（始终为已拒绝）或 `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST`（始终为审核中）。与已通过用户的匹配会触发 `FRONT_CAMERA_DUPLICATED_FACE` 或 `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`；如果该已通过用户使用了不同的姓名进行验证，还会额外触发 `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH`；如果该用户的身份证件显示不同的出生日期，则会触发 `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`。请参阅[身份证件验证警告](https://docs.didit.me/zh/core-technology/id-verification/warnings-id-verification.md)。
- 匹配项列在会话详情的身份证件验证卡片中，并在[会话决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)的 `id_verifications[].document_selfie_face_matches` 中返回。它采用与 `liveness_checks[].matches` 相同的条目格式。对于较早的会话或未运行搜索的情况，该字段为 `null`；当搜索已运行但未发现任何内容时，该字段为空数组。`match_image_url` 是一个会过期的预签名 URL。
- 仅使用自拍照中最大的人脸，且仅在检测器确定其为人脸时使用。每份证件仅搜索一张自拍照：正面自拍照，或者当正面自拍照中没有清晰人脸时的背面自拍照。
- 该自拍照仅用于比对。其生物特征模板绝不会被存储，因此后续会话绝不会与它进行匹配。若要根据会话自拍照封禁某人，请从会话页面将其添加到您的人脸黑名单中。该搜索在**身份证件验证**步骤中拥有独立的开关和操作，位于该步骤的**规则**选项卡（**静默采集人脸搜索**）中，或通过[工作流功能配置](https://docs.didit.me/zh/management-api/workflows/feature-configs.md#ocr-/-身份证件验证)中的 `document_selfie_face_search_enabled` 和 `document_selfie_duplicated_face_*` 操作进行配置。它默认处于开启状态；重复人脸操作默认为已通过（警告仍会报告），姓名和证件交叉核验默认为审核中，与活体检测中的对应操作类似。该搜索需要自拍照，因此仅在开启静默采集时运行。在“活体检测”步骤中关闭人脸搜索也会同时关闭此搜索：该选择退出的决定针对该用户的人脸，因此涵盖该会话的所有自拍照。### 证件不匹配规则**证件不匹配**规则（活体自拍照为 `DUPLICATED_FACE_DOCUMENT_MISMATCH`，静默采集为 `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`）仅在匹配用户的身份证件显示不同的出生日期时，才会标记重复人脸。
同一人出示不同的证件（例如先出示身份证后出示护照）不会被标记。
更换新证件也不会被标记。
两个会话使用了同一国家/地区签发的相同证件号码时，绝不会被标记。### 关闭自动人脸搜索每个“活体检测”步骤默认都会开启自动人脸搜索。如果出于隐私考虑，您可以在 Business Console（简易模式和高级模式）中，通过**活体检测**步骤的**规则**选项卡按工作流将其关闭，或者在[工作流功能配置](https://docs.didit.me/zh/management-api/workflows/feature-configs.md#活体检测)中通过 `LIVENESS` 或 `AGE_ESTIMATION` 节点上的 `face_search_enabled: false` 进行关闭。关闭该开关后，活体自拍照仍会进行活体评分，并在人脸比对中与证件肖像进行 1:1 比对，但绝不会进入人脸索引：- 系统不会运行任何搜索，因此会话不会获得重复、黑名单或白名单结论，其 `liveness_checks[].matches` 保持为空。**重复人脸**、**姓名不匹配**、**证件不匹配**以及跨组织人脸规则不会有任何内容可供其执行，并在 Console 中隐藏。
- 自拍照不会存储任何生物特征模板，因此后续会话无法与此会话进行比对，会话被删除后[生物特征模板保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)也不会保留任何内容。
- 自拍照不会用于在跨组织检查中确定共享生物特征对应的人员。
- 证件采集期间拍摄的自拍照也不会被搜索（无 `FRONT_CAMERA_*` 黑名单或重复风险）：选择退出涵盖该会话的所有自拍照。身份证件验证步骤自带的开关（见上文）也可以单独关闭该搜索。**开关属于哪个步骤。** 该开关位于采集自拍照的步骤上，因此**活体检测**或**年龄估算**步骤分别控制自身的人脸搜索设置。**人脸比对**步骤本身没有开关：当用户在该步骤重拍自拍照时（例如在您要求其重新提交该步骤后），重拍将遵循“活体检测”步骤的设置，因此选择退出也会将新自拍照排除在索引之外。如果您的工作流分支到多个“活体检测”步骤，则适用的设置为会话实际经历的分支上的设置，跨组织人脸识别也遵循同一步骤。现有工作流将保持当前行为，直到您主动退出。此变更适用于保存工作流后启动的会话；较早会话存储的模板将保留在索引中，直到这些会话被删除或清除。该开关不会影响您显式调用的独立 [Face Search API](https://docs.didit.me/zh/standalone-apis/face-search.md)。> [!WARNING]
>
> 您的人脸黑名单在验证过程中通过相同的 1:N 搜索执行。如果活体检测步骤中的人脸搜索处于关闭状态，被列入黑名单的人既不会在该步骤中被发现，也不会通过证件采集期间拍摄的自拍照被发现；如果在身份证件验证步骤中关闭静默捕获人脸搜索，也不会通过该自拍照被发现。### API 访问人脸搜索功能也可通过我们的 [API](https://docs.didit.me/zh/standalone-apis/face-search.md) 使用，允许您：- 通过编程方式提交人脸搜索
- 将人脸比对功能集成到您自己的应用中
- 构建自定义欺诈检测工作流
- 创建用于重复检测的自动化系统## 主要功能- **高准确率**：先进的生物识别算法提供可靠的比对结果
- **可配置阈值**：根据您的风险承受能力自定义匹配敏感度
- **全面扫描**：在您所有的已验证用户中进行搜索
- **快速返回结果**：即使面对庞大的用户数据库也能快速处理搜索
- **注重隐私**：比对使用限定在您应用范围内的数字化人脸模板；索引绝不会离开您的租户### 可配置阈值您可以通过为相似度分数设置不同的阈值来自定义搜索敏感度：> [!NOTE]
>
> 这些阈值可以根据您的风险承受能力和安全要求进行调整。## 工作原理**1. 人脸提取**当发起搜索时，系统会处理参考图像：| 流程 | 说明 |
| - | - |
| **特征提取** | 从参考图像中分离面部特征 |
| **归一化** | 标准化面部数据以实现一致的比对 |
| **质量验证** | 检查图像质量和面部清晰度 |
| **向量编码** | 创建人脸的数学向量表示 |**2. 比对算法**系统会在您已验证会话的整个数据库中进行搜索：- 将参考面部向量与**您应用中注册的每张人脸**进行比对：会话人脸、上传到用户个人资料的人脸、您的人脸名单以及任何保留的生物特征模板
- 采用针对速度和准确率进行优化的先进神经网络架构
- 支持两种搜索模式：**最相似**（排序列表）和**已列入黑名单或已通过**（按状态过滤）
- 利用优化索引快速处理大型数据库**3. 相似度评分**针对每次比对，系统都会生成一个相似度百分比：| 分数区间 | 解读 |
| :-: | - |
| **90%+** | 高度匹配 — 极有可能是同一个人 |
| **70–89%** | 可能匹配 — 可能需要人工审核 |
| **低于 70%** | 可能是不同个体 |您配置的匹配阈值决定了哪些结果会被标记。**4. 结果交付**系统返回完整的结果集：- 按相似度分数排序的潜在匹配**排序列表**
- 包含会话 ID、验证日期和供应商数据的**匹配详情**
- 每个匹配项的**相似度百分比**
- 可用于人工复核的**匹配图像**
- 指示匹配人脸是否已被列入黑名单的**黑名单状态**## 已删除的会话和保留的生物特征模板默认情况下，删除会话会同时删除其人脸特征向量，因此该用户会从索引中移除，并且可以在没有重复标记的情况下再次验证。在通过后很快删除会话但仍需要防范重复注册的应用可以启用[生物特征模板保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)。启用后，Didit 会在会话删除后保留一个与用户绑定的无图像生物特征模板，并且该模板参与人脸搜索和自动重复检测的方式与活跃会话中的人脸完全相同。命中保留模板时报告的内容包含 `source: "retained_template"`、所属用户的 `vendor_user_id` 和 `vendor_data`，以及一个 `biometric_template_id`。它不包含会话 ID、匹配图像、身份详情或会话状态，因为生成该人脸的会话已不存在。保留模板绝不会被列入黑名单；人脸黑名单条目保留其自身独立的生物特征条目。该模板会一直保留，直至预定的到期日期、用户被删除、收到隐私擦除请求，或通过 [Biometric Templates API](https://docs.didit.me/zh/management-api/biometric-templates/overview.md) 或控制台中的 **名单 → 生物特征模板** 显式清除。## 相似度百分比相似度百分比是用于确定潜在匹配的核心指标：- **高百分比（通常为 90% 及以上）**：表示人脸属于同一人的可能性极高。
- **中等百分比（70-89%）**：提示可能匹配，可能需要进一步审核。
- **低百分比（低于 70%）**：很可能表示不同的人。构成“匹配”的确切阈值可以根据您的安全要求进行配置。提高阈值可以减少误报，但可能会增加漏报。## 使用场景- **欺诈预防**：识别试图创建多个账户的用户
- **增强型 KYC**：为您的 KYC 流程增加额外的验证层
- **合规要求**：满足检测重复账户的监管要求
- **门禁管理**：针对高安全级别区域验证用户的真实性
- **执法**：协助授权机构识别目标人员


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