人脸搜索 1:N：发现一个人控制的所有账户 (ZH)

在您平台上运行四十个账户的操作员拥有四十个电子邮件地址、可能四十种支付工具，以及可能四十台设备。但他们没有四十张脸。

如果您的访问流程的任何部分捕获了自拍，您就已经掌握了真正难以复制的唯一标识符。人脸搜索 1:N 就是利用这一点的调用——一个请求，一张人脸，然后返回该用户在您自己系统中验证过的所有账户。

它与 Didit 身份验证免费提供，在不到两秒内返回结果，并在验证会话期间的活体检测中自动运行。

主要收获

• POST /v3/face-search/ 对比您自己的应用程序已注册的人脸进行搜索——使用 save_api_request=true 运行的会话——而不是共享的全局索引。
• 匹配结果会返回每个匹配项上您自己的 vendor_data，因此结果可以直接映射到您的账户 ID。
• 两种模式：most_similar 用于去重和识别回访用户，blocklisted_or_approved 用于黑名单筛选。
• status 仅在黑名单匹配时为 "Declined"。重复项返回 "Approved" 并带有 DUPLICATED_FACE 警告——按设计为信息性，因为去重策略由您决定。
• 响应是一个单一的 face_search 对象，而不是一个数组。这一点容易让人困惑。
• Didit 验证免费提供。响应时间不到两秒。在活体检测期间自动运行。

1:N 的含义及其为何是正确的工具

1:1 人脸匹配回答的是“这是文档中的那个人吗？”这是一个验证问题，它在注册过程中运行。

1:N 搜索回答的是一个不同的问题：“在我已经验证过的所有人中，这是其中之一吗？”输入一张图片，您的索引中的所有匹配项都会输出。

对于协同账户滥用，第二个问题才是关键。Anthropic 关于蒸馏活动的报告描述了通过关系信号（共享支付方式、协调时间、共享基础设施）构建的归因。生物识别 1:N 搜索属于同一类信号，来源于操作员必须复制的最昂贵标识符。

索引是您的。人脸搜索根据您自己的应用程序通过先前验证（使用 save_api_request=true 的会话，或使用 save_api_request=true 的被动活体检测）注册的人脸运行。它不是对其他 Didit 客户用户进行搜索。如果您没有注册人脸，则无物可搜。

API

请求

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=acct_8842'

multipart/form-data，使用 x-api-key 进行认证。

必需：user_image — jpg、jpeg、png、tiff 或 webp 格式，最大 5 MB。不接受 PDF。图片必须包含至少一张可检测到的人脸；如果存在多张人脸，则以最大的边界框为准。

可选：

• search_type — most_similar（默认）用于去重和回访用户检测，或 blocklisted_or_approved 用于黑名单筛选。
• save_api_request — 将此图片注册到您的索引中。
• vendor_data — 您自己的主体标识符。

响应

响应携带一个单一的 face_search 对象。大多数 Didit 功能返回复数数组，因此在编写解析器之前，这种形状值得仔细阅读。

{
  "request_id": "...",
  "face_search": {
    "status": "Approved",
    "total_matches": 12,
    "matches": [
      {
        "session_id": "...",
        "session_number": 4471,
        "similarity_percentage": 97.4,
        "vendor_data": "acct_3310",
        "verification_date": "2026-06-02T09:14:00Z",
        "user_details": { },
        "match_image_url": "...",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": { "entities": [] },
    "warnings": []
  }
}

用于调查的字段：

• total_matches — 共享此人脸的账户数量。
• 每个匹配项上的vendor_data — 您的标识符，因此匹配列表立即成为账户列表。
• similarity_percentage — 每个单独匹配的强度。
• verification_date — 时间线。在十一个月内验证的十二个账户与在一个下午验证的十二个账户读取方式不同。
• is_blocklisted — 此匹配项是否已在您的黑名单中。
• session_id — 枢纽，可查看该会话捕获的所有其他信息，包括其设备和网络警告。

状态语义

这是整个端点中最重要的行为：

status 仅在找到至少一个黑名单匹配时为 "Declined"。纯重复匹配返回 "Approved"。

重复不是拒绝。它是信息。Didit 故意拒绝为您做出重复决策，因为重复可能有合理解释，并且只有您知道您产品的规则。

警告

警告	含义
FACE_IN_BLOCKLIST	明确的黑名单匹配——拒绝
POSSIBLE_FACE_IN_BLOCKLIST	低于硬性阈值的边缘匹配——转入人工审核
DUPLICATED_FACE	此人脸已在不同的 vendor_data 下验证
POSSIBLE_DUPLICATED_FACE	边缘重复
MULTIPLE_FACES_DETECTED	提交的图片中检测到多张人脸

故障模式

• HTTP 400 — user_image 中未检测到人脸。要求重拍。
• HTTP 403 — 积分不足。
• status: "Declined" 带有 FACE_IN_BLOCKLIST — 明确命中。拒绝。
• POSSIBLE_FACE_IN_BLOCKLIST — 低于硬性阈值。人工审核。
• DUPLICATED_FACE — 已在不同的 vendor_data 下验证。根据您的策略合并、阻止或允许。

自动路径

您通常根本不需要调用端点。人脸搜索在验证会话期间的活体检测中自动运行：

• 面部生物识别信息与所有先前验证的用户进行比较。
• 通过面部相似性识别潜在的重复账户。
• 根据您配置的相似性阈值标记匹配项。
• 人脸会与您的黑名单进行比对，黑名单匹配会自动拒绝验证。

因此，对于您已经运行完整验证的任何级别，重复检测都无需额外费用和额外调用。独立端点适用于会话流程未涵盖的情况——事后调查账户、筛选您通过其他方式获得的图像，或者切换 search_type 以对您已有的图像进行黑名单重点搜索。

将匹配项转换为行为者图谱

从一个可疑账户开始的实际工作流程：

1. 搜索人脸。total_matches: 12 — 十二个账户，一个人。
2. 读取 vendor_data。十二个您自己的账户 ID，无需连接。
3. 读取时间线。聚类 verification_date 值。爆发式创建的账户与多年来创建的账户在操作上有所不同。
4. 以 session_id 为轴。提取每个会话的设备和网络警告。共享 DUPLICATED_DEVICE_FINGERPRINT 的人脸会使聚类更紧密；在不相关设备上的账户可能是不同的安排。
5. 扩展。步骤 4 中浮现的设备和 IP 范围将引入人脸搜索遗漏的账户——因为是不同的人完成了这些检查。
6. 一次决定，跨标识符强制执行。如果确认集群存在滥用行为，请将确认的 reference_session_id 发布到您关心的每个条目类型黑名单——人脸、设备、IP、电子邮件、电话、文档。每个列表只需一次调用，每次调用都会从该会话中自动提取正确的值，因此无需手动重新输入任何内容。

六个步骤，一个起点，并且没有任何即时检查。流量层告诉您此账户有问题。这告诉您实际有多少个账户。

值得明确指出：1:N 人脸搜索不能防止模型提取，也无法检测到它。人脸搜索无法查看您的 API 流量。它将账户解析为个人，这使您能够对整个集群的警报采取行动，而不是仅仅一行。模型级输出控制和语义流量检测是独立的层，它们仍然是模型提供商的责任。

用例

AI API 平台将行为警报解析为操作员控制的完整账户集。

免费套餐和信用滥用——一个人拥有多个试用账户，这是具有较低风险的相同检测问题。

市场和零工平台捕获被禁止的卖家、司机或快递员重新注册。

iGaming 强制执行单一账户规则和自我排除，其中回访的被排除玩家是监管失败，而不仅仅是滥用案例。

金融服务识别合成身份环，其中一个真实人脸分散在许多伪造身份中。

常见问题

我的人脸索引是否与其他 Didit 客户共享？

不。人脸搜索根据您自己的应用程序通过您自己的验证构建的索引运行。它不是跨客户搜索。

什么控制着人脸进入索引？

验证会话或被动活体检测调用上的 save_api_request=true。您决定注册什么以及控制保留，这与您自己的隐私声明和处理生物识别数据的法律依据一致。

我应该使用什么相似性阈值？

请注意调整适用于何处。在独立端点上，将确认命中（FACE_IN_BLOCKLIST、DUPLICATED_FACE）与可能命中（POSSIBLE_FACE_IN_BLOCKLIST、POSSIBLE_DUPLICATED_FACE）分开的相似性范围是内部固定的——每个应用程序的阈值调整适用于工作流活体检测，而不适用于 POST /v3/face-search/。因此，在独立路径上，读取每个匹配项的 similarity_percentage 并在应用程序逻辑中应用您自己的标准，并将 POSSIBLE_* 警告视为您的审核队列而不是拒绝队列。

大规模运行速度如何？

不到两秒的响应时间。

我可以搜索从未经过 Didit 验证的人脸吗？

可以。任何接受格式的 user_image 都可以。如果未检测到人脸，则调用返回 HTTP 400。

它真的免费吗？

是的——人脸搜索 1:N 与 Didit 身份验证免费提供。没有按次搜索收费。您支付的是构建索引的验证费用，完整套餐为 0.33 美元，每月前 500 次免费。

如果同一个人合法拥有两个账户怎么办？

那么 DUPLICATED_FACE 正是它旨在提供的信息信号——这就是它不拒绝的原因。根据您产品的规则，合并它们、允许它们或询问用户。

准备好开始了吗？

人脸搜索在每个 Didit 账户上都可用，无需单独购买产品。

• 阅读文档 — 人脸搜索 1:N 概述和列表 API 用于人脸黑名单。
• 查看产品 — 用户验证。
• 查看定价 — 人脸搜索 1:N 免费；构建索引的验证套餐为 0.33 美元。
• 免费开始 — business.didit.me，每月 500 次 KYC 验证免费。