didit-face-search

Didit 人脸搜索 API（1:N）

概述

将图像中最大的人脸与应用的人脸搜索索引进行比对，并返回相似度高于最低阈值的最多 5 个排序结果，以及黑名单和重复项警告。

**搜索范围：**来自任意状态验证会话的人脸、已保存的独立调用（例如，使用 save_api_request=true 的 Passive Liveness 或 Age Estimation）、直接上传到 User 个人资料的人脸、列表中的人脸（黑名单、允许名单），以及选择保留在 User 上的无图像生物特征模板。先前 Face Search 调用录入的人脸永远不会作为结果返回，因此重复搜索不会相互匹配。

搜索模式（search_type）：

• most_similar（默认）：按相似度对所有已录入人脸排序。用于去重和调查欺诈团伙。
• blocklisted_or_approved：仅搜索黑名单人脸、允许名单人脸、已通过审核会话中的人脸、导入的 User 人脸和保留的模板，并将黑名单条目排在首位。用于黑名单筛查。

主要限制：

• 允许的文件扩展名：tiff、jpg、jpeg、png、webp（不支持 PDF）
• 最大文件大小：5 MB（图像会先压缩到约 0.5 MB 再进行处理）
• 图像必须包含可检测的人脸，否则返回 HTTP 400 {"error": "No face detected in the image"}
• 如果图像中有多张人脸，则搜索最大的一张，并添加 MULTIPLE_FACES_DETECTED
• vendor_data 不会从结果中排除同一用户先前的人脸（与 Passive Liveness 不同）

价格：$0.05（每次成功调用；独立调用没有免费额度）。以下为截至 2026 年 11 月 1 日的标价，届时 Didit 将调整定价，每月 500 次免费检查将变为每月 $10 免费额度。请访问 didit.me/pricing 查看当前价格。

**判定：**仅当触发 FACE_IN_BLOCKLIST 或 POSSIBLE_FACE_IN_BLOCKLIST 时才会判定为 Declined；否则为 Approved。重复项和多脸警告不会导致拒绝，也没有 In Review 状态。Approved 不代表该人脸是新的：请检查 total_matches 和重复项警告。此端点不会返回活体检测结论（请使用 didit-liveness-detection）。

**保存和录入（save_api_request，默认值为 true）：**该调用会保存为 API 会话（Business Console、GET /v3/session/{request_id}/decision/、status.updated webhook），match_image_url 的值为预签名 URL，且搜索到的人脸会录入索引（但不会在之后的搜索中返回）。设置为 false 时不会存储任何内容，也不会录入人脸，match_image_url 的值则为无法下载的内部存储路径。

**相似度参考：**Face Search 文档将 90% 及以上视为很可能是同一人，将 70-89% 视为可能匹配，可能需要审核。Didit 自身的判定依据是警告：强匹配会触发 DUPLICATED_FACE / FACE_IN_BLOCKLIST，较弱匹配会触发 POSSIBLE_DUPLICATED_FACE / POSSIBLE_FACE_IN_BLOCKLIST。

**沙盒：**沙盒 API 密钥在请求验证后会返回静态的 Approved 载荷；不会保存任何内容，也不会收费。

**API 参考：**https://docs.didit.me/standalone-apis/face-search **功能指南：**https://docs.didit.me/core-technology/face-search/overview

---

身份验证

每个请求都需要 x-api-key 标头。请使用 Didit Business Console 中 Developers > API keys 下的应用 API 密钥，或以编程方式创建账户和密钥（参见 Getting Started）。具有自定义访问权限的命名密钥需要 Sessions 写入权限才能运行独立检查；受限于特定工作流或仅限已通过审核会话的密钥无法运行这些检查。

快速开始（还没有账户？）

如果你还没有 Didit API 密钥，可通过 2 次 API 调用创建一个：

1. 注册： 使用 {"email": "[email protected]", "password": "MyStr0ng!Pass"} 调用 POST https://apx.didit.me/auth/v2/programmatic/register/
2. 检查邮箱，获取 6 位验证码
3. 验证： 使用 {"email": "[email protected]", "code": "A3K9F2"} 调用 POST https://apx.didit.me/auth/v2/programmatic/verify-email/。密钥位于响应中的 application.api_key。

添加额度： 使用 GET /v3/billing/balance/ 查看余额；使用 POST /v3/billing/top-up/ 并传入 {"amount_in_dollars": 50} 获取 Stripe 结账链接。

如需全面的平台管理（工作流、会话、用户、账单），请参阅 didit-verification-management 技能。

---

端点

POST https://verification.didit.me/v3/face-search/

请求头

请求头	值	必填
x-api-key	你的 API 密钥	是
Content-Type	multipart/form-data（由你的 HTTP 客户端设置）	是

请求参数（multipart/form-data）

参数	类型	必填	默认值	说明
user_image	文件	是	-	要搜索的人脸图像（tiff/jpg/jpeg/png/webp，最大 5 MB）
search_type	字符串	否	most_similar	most_similar 或 blocklisted_or_approved（参见概述）
rotate_image	布尔值	否	false	尝试旋转 90 度，并使用人脸检测效果最佳的方向。会增加延迟
save_api_request	布尔值	否	true	保存为 API 会话并录入搜索到的人脸（参见概述）
vendor_data	字符串	否	-	你的用户标识符，会被存储并在响应中返回。不会用于筛选结果
metadata	JSON 对象	否	-	与会话一同存储（保存时），并在响应中返回。在 multipart 中以 JSON 编码的字符串形式发送

示例

import requests

with open("photo.jpg", "rb") as f:
    response = requests.post(
        "https://verification.didit.me/v3/face-search/",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"user_image": ("photo.jpg", f, "image/jpeg")},
        data={"search_type": "most_similar", "vendor_data": "user-123"},
        timeout=60,
    )
response.raise_for_status()
result = response.json()["face_search"]
for match in result["matches"]:
    print(match["similarity_percentage"], match["source"], match["session_id"], match["is_blocklisted"])

const formData = new FormData();
formData.append("user_image", photoFile);
formData.append("search_type", "most_similar");

const response = await fetch("https://verification.didit.me/v3/face-search/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});
const { face_search } = await response.json();

响应（200 OK）

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 97.31,
        "source": "session",
        "vendor_data": "user-1",
        "vendor_user_id": "2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4",
        "biometric_template_id": null,
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {"bbox": [40, 40, 120, 120], "confidence": 0.732973}
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "duplicated_session_number": 323442,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

状态值与处理方式

状态	含义	操作
"Approved"	未命中阻止名单	在将用户视为新用户之前，检查 total_matches 和 DUPLICATED_FACE / POSSIBLE_DUPLICATED_FACE
"Declined"	触发了 FACE_IN_BLOCKLIST 或 POSSIBLE_FACE_IN_BLOCKLIST	阻止或审核；请查看 matches[].is_blocklisted 和警告中的 additional_data

错误响应

代码	含义	操作
400	请求无效	查看响应正文中的字段错误
400	{"error": "No face detected in the image"}	请用户提供一张包含单张清晰正面人脸的新图像（或使用 rotate_image=true 重试）
401	API 密钥已过期	轮换密钥，或在 Developers > API keys 中创建新密钥
403	缺少、错误或已撤销的 API 密钥；无权访问此端点的受限密钥；请求来自密钥 IP 允许列表之外；或额度不足	查看 detail 或 error 中的信息：修正 x-api-key 请求头或密钥权限，或充值
429	速率限制：每个密钥每分钟最多 300 次 POST/PATCH/DELETE 请求和 600 次 GET 请求	等待 Retry-After 指定的秒数后重试

---

响应字段参考

顶层

字段	类型	描述
request_id	uuid	当 save_api_request=true 时的会话 ID（与 GET /v3/session/{request_id}/decision/ 配合使用）；否则为一次性关联 ID
face_search.status	string	"Approved" 或 "Declined"
face_search.total_matches	integer	matches 中条目的数量（0 至 5）
face_search.matches[]	array	最多 5 个匹配项，按相似度排序（blocklisted_or_approved 中的条目优先）。没有足够相似的结果时为空
face_search.user_image.entities[]	array	每张检测到的人脸对应一个条目，仅包含 bbox [x_min, y_min, x_max, y_max] 和 confidence（0-1）
face_search.user_image.best_angle	integer	检测效果最佳时的旋转角度（度）；除非 rotate_image=true 对图像进行了校正，否则为 0
face_search.warnings[]	array	{risk, feature, additional_data, log_type, short_description, long_description}。feature 始终为 LIVENESS
vendor_data / metadata	string / object or null	对你所发送内容的回显
created_at	string	响应时间，采用 ISO 8601 UTC 格式

匹配对象

字段	类型	描述
similarity_percentage	float	你的人脸与匹配人脸之间的相似度，范围为 0-100
source	string	session（验证会话或已保存的独立调用）、imported（上传至 User 资料的人脸）、list_entry（你某个列表中的人脸）、retained_template（保留的无图像模板，参见 /v3/biometric-templates/）
session_id	uuid or null	匹配的会话。imported 和 retained_template 时为 null；对于 list_entry，为该条目来源的会话（如有）
session_number	integer or null	Business Console 中显示的会话编号，规则与 session_id 相同
vendor_data	string or null	匹配会话的 vendor_data；对于 imported / retained_template，则为关联 User 的 vendor_data
vendor_user_id	uuid or null	关联 User 的 ID。对于列表条目以及未关联 User 的会话，为 null
biometric_template_id	uuid or null	仅对 retained_template 设置
verification_date	string or null	匹配人脸的采集时间（YYYY-MM-DDThh:mm:ssZ）。对于 list_entry 为 null
user_details	object or null	来自匹配会话文档验证的 {full_name, document_type, document_number}。imported 匹配项仅包含 full_name。没有身份数据时（例如仅进行活体检测的会话）以及对于 retained_template，为 null
match_image_url	string or null	当 save_api_request=true 时，匹配人脸的限时 URL（默认 4 小时）；当其为 false 时，为内部存储路径；对于 retained_template 为 null
status	string or null	匹配会话的状态（Approved、Declined、In Review 等）。非会话匹配时为 null
is_blocklisted	boolean	匹配的人脸是否位于你的人脸阻止名单中
is_allowlisted	boolean	匹配的人脸是否位于你的某个许可名单中。许可名单中的匹配项会抑制重复警告
api_service	string or null	匹配人脸来自独立 API 调用时设置（例如 PASSIVE_LIVENESS）

---

警告标签

标签	严重程度	是否拒绝	触发条件
FACE_IN_BLOCKLIST	error	是	与人脸屏蔽名单中的人脸高度匹配。additional_data 包含 blocklisted_session_id、blocklisted_session_number、api_service
POSSIBLE_FACE_IN_BLOCKLIST	error	是	与人脸屏蔽名单中的人脸匹配度较低
MULTIPLE_FACES_DETECTED	warning	否	检测到多张人脸；已搜索其中最大的一张
DUPLICATED_FACE	information	否	与来自已批准会话、导入的人脸或保留的模板的人脸高度匹配。出现 FACE_IN_BLOCKLIST 时不会触发。additional_data 包含 duplicated_session_id、duplicated_session_number、api_service
POSSIBLE_DUPLICATED_FACE	information	否	与同类人脸的匹配度较低。出现 POSSIBLE_FACE_IN_BLOCKLIST 时不会触发

• 没有 NO_FACE_DETECTED 警告：不含人脸的图像会返回 HTTP 400。
• 根据 status、warnings[].risk 和 matches[] 作出判断；将每条警告中回显的 log_type 视为信息。
• 使用 Lists API 管理人脸屏蔽名单和允许名单（参见 didit-verification-management）。

---

常见工作流

重复账户检测

1. New user signs up -> POST /v3/face-search/ with the selfie (search_type=most_similar)
2. status "Declined" -> blocklisted face: reject or send to manual review
3. DUPLICATED_FACE / POSSIBLE_DUPLICATED_FACE -> the face already passed on another account:
   compare matches[].vendor_data / vendor_user_id with the current user, then investigate
4. total_matches == 0 -> no similar face is enrolled

仅进行屏蔽名单筛查

1. POST /v3/face-search/ with search_type=blocklisted_or_approved
2. "Declined" -> blocklist hit (matches[] lists blocklisted entries first)

验证与去重相结合

1. POST /v3/face-search/ -> check for existing accounts (run it BEFORE any call that saves this selfie)
2. POST /v3/passive-liveness/ -> verify the user is live (also enrolls the face when saved)
3. POST /v3/id-verification/ -> verify the identity document
4. POST /v3/face-match/ -> compare the selfie to the document portrait
5. All Approved and no duplicate warning -> verified, unique, real user

先运行搜索：Passive Liveness 或 Age Estimation 已保存到索引中的自拍照，会以接近 100% 的匹配度返回，其 api_service 会标明对应的独立 API（例如 PASSIVE_LIVENESS）。

安全性： 匹配图像 URL 默认会在 4 小时后过期。仅存储 request_id、session_id 和 similarity_percentage；请勿将生物特征图像保存在自己的服务器上。

---

实用脚本

search_faces.py：从命令行搜索匹配的人脸。

# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/search_faces.py selfie.jpg
python scripts/search_faces.py photo.png --search-type blocklisted_or_approved
python scripts/search_faces.py photo.png --rotate --vendor-data user-123 --no-save