didit-face-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Didit Face Search API (1:N)

Didit Face Search API（1:N）

Overview

概述

Compares a reference face against all previously approved verification sessions to detect duplicate accounts and blocklisted faces. Returns ranked matches with similarity scores.

Key constraints:

Supported formats: JPEG, PNG, WebP, TIFF
Maximum file size: 5MB
Compares against all approved sessions in your application
Blocklist matches cause automatic decline

Similarity score guidance:

Range	Interpretation
90%+	Strong likelihood of same person
70-89%	Possible match, may need manual review
Below 70%	Likely different individuals

API Reference: https://docs.didit.me/standalone-apis/face-search Feature Guide: https://docs.didit.me/core-technology/face-search/overview

将参考人脸与所有已通过的验证会话进行比对，以检测重复账户和黑名单中的人脸。返回带有相似度分数的排序匹配结果。

关键限制：

支持格式：JPEG、PNG、WebP、TIFF
最大文件大小：5MB
与应用中所有已通过的会话进行比对
命中黑名单会导致自动拒绝

相似度分数参考：

范围	解读
90%+	极大概率为同一人
70-89%	可能匹配，需人工审核
低于70%	大概率为不同个体

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

Authentication

身份验证

All requests require

x-api-key

header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).

所有请求均需携带

x-api-key

请求头。可从Didit企业控制台 → API与Webhooks获取密钥，或通过程序化注册获取（见下文）。

Getting Started (No Account Yet?)

快速入门（还没有账户？）

If you don't have a Didit API key, create one in 2 API calls:

Register:

POST https://apx.didit.me/auth/v2/programmatic/register/

with

{"email": "you@gmail.com", "password": "MyStr0ng!Pass"}

Check email for a 6-character OTP code

Verify:

POST https://apx.didit.me/auth/v2/programmatic/verify-email/

with

{"email": "you@gmail.com", "code": "A3K9F2"}

→ response includes

api_key

To add credits:

GET /v3/billing/balance/

to check,

POST /v3/billing/top-up/

with

{"amount_in_dollars": 50}

for a Stripe checkout link.

See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).

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

注册： 向

POST https://apx.didit.me/auth/v2/programmatic/register/

发送请求，参数为

{"email": "you@gmail.com", "password": "MyStr0ng!Pass"}

查收邮件获取6位OTP验证码

验证： 向

POST https://apx.didit.me/auth/v2/programmatic/verify-email/

发送请求，参数为

{"email": "you@gmail.com", "code": "A3K9F2"}

→ 响应结果包含

api_key

充值方式： 调用

GET /v3/billing/balance/

查询余额，调用

POST /v3/billing/top-up/

并携带

{"amount_in_dollars": 50}

获取Stripe结账链接。

如需完整的平台管理（工作流、会话、用户、账单），请查看didit-verification-management技能。

Endpoint

接口地址

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

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

Headers

请求头

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	`multipart/form-data`	Yes

请求头	值	是否必填
`x-api-key`	您的API密钥	是
`Content-Type`	`multipart/form-data`	是

Request Parameters (multipart/form-data)

请求参数（multipart/form-data）

Parameter	Type	Required	Default	Description
`user_image`	file	Yes	—	Face image to search (JPEG/PNG/WebP/TIFF, max 5MB)
`rotate_image`	boolean	No	`false`	Try 0/90/180/270 rotations for non-upright faces
`save_api_request`	boolean	No	`true`	Save in Business Console
`vendor_data`	string	No	—	Your identifier for session tracking

参数	类型	是否必填	默认值	说明
`user_image`	文件	是	—	待搜索的人脸图片（JPEG/PNG/WebP/TIFF格式，最大5MB）
`rotate_image`	布尔值	否	`false`	尝试对非正脸图片进行0/90/180/270度旋转
`save_api_request`	布尔值	否	`true`	在企业控制台中保存请求记录
`vendor_data`	字符串	否	—	用于会话追踪的自定义标识

Example

示例

python

import requests

response = requests.post(
    "https://verification.didit.me/v3/face-search/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"user_image": ("photo.jpg", open("photo.jpg", "rb"), "image/jpeg")},
)
print(response.json())

typescript

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

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

python

import requests

response = requests.post(
    "https://verification.didit.me/v3/face-search/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"user_image": ("photo.jpg", open("photo.jpg", "rb"), "image/jpeg")},
)
print(response.json())

typescript

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

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

Response (200 OK)

响应结果（200 OK）

json

{
  "request_id": "a1b2c3d4-...",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "uuid-...",
        "session_number": 1234,
        "similarity_percentage": 95.2,
        "vendor_data": "user-456",
        "verification_date": "2025-06-10T10:30:00Z",
        "user_details": {
          "name": "Elena Martinez",
          "document_type": "Identity Card",
          "document_number": "***456"
        },
        "match_image_url": "https://example.com/match.jpg",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": {
      "entities": [
        {"age": "27.6", "bbox": [40, 40, 120, 120], "confidence": 0.95, "gender": "female"}
      ],
      "best_angle": 0
    },
    "warnings": []
  }
}

json

{
  "request_id": "a1b2c3d4-...",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "uuid-...",
        "session_number": 1234,
        "similarity_percentage": 95.2,
        "vendor_data": "user-456",
        "verification_date": "2025-06-10T10:30:00Z",
        "user_details": {
          "name": "Elena Martinez",
          "document_type": "Identity Card",
          "document_number": "***456"
        },
        "match_image_url": "https://example.com/match.jpg",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": {
      "entities": [
        {"age": "27.6", "bbox": [40, 40, 120, 120], "confidence": 0.95, "gender": "female"}
      ],
      "best_angle": 0
    },
    "warnings": []
  }
}

Status Values & Handling

状态值与处理方式

Status	Meaning	Action
`"Approved"`	No concerning matches found	Proceed — new unique user
`"In Review"`	Matches above similarity threshold	Review `matches[]` for potential duplicates
`"Declined"`	Blocklist match or policy violation	Check `matches[].is_blocklisted` and `warnings`

状态	含义	操作
`"Approved"`	未发现可疑匹配	继续流程 — 新用户为唯一账户
`"In Review"`	存在超过相似度阈值的匹配	查看 `matches[]` 以排查潜在重复账户
`"Declined"`	命中黑名单或违反规则	检查 `matches[].is_blocklisted` 和 `warnings` 字段

Error Responses

错误响应

Code	Meaning	Action
`400`	Invalid request	Check file format, size, parameters
`401`	Invalid API key	Verify `x-api-key` header
`403`	Insufficient credits	Top up at business.didit.me

状态码	含义	操作
`400`	请求无效	检查文件格式、大小和参数
`401`	API密钥无效	验证 `x-api-key` 请求头
`403`	余额不足	在business.didit.me进行充值

Response Field Reference

响应字段参考

Match Object

匹配对象

Field	Type	Description
`session_id`	string	UUID of the matching session
`session_number`	integer	Session number
`similarity_percentage`	float	0-100 similarity score
`vendor_data`	string	Your reference from the matching session
`verification_date`	string	ISO 8601 timestamp
`user_details.name`	string	Name from the matching session
`user_details.document_type`	string	Document type used
`user_details.document_number`	string	Partially masked document number
`match_image_url`	string	Temporary URL (expires 60 min)
`status`	string	Status of the matching session
`is_blocklisted`	boolean	Whether the match is from the blocklist

字段	类型	说明
`session_id`	字符串	匹配会话的UUID
`session_number`	整数	会话编号
`similarity_percentage`	浮点数	0-100的相似度分数
`vendor_data`	字符串	匹配会话中的自定义标识
`verification_date`	字符串	ISO 8601时间戳
`user_details.name`	字符串	匹配会话中的用户姓名
`user_details.document_type`	字符串	所用证件类型
`user_details.document_number`	字符串	部分掩码的证件号码
`match_image_url`	字符串	临时URL（60分钟后过期）
`status`	字符串	匹配会话的状态
`is_blocklisted`	布尔值	该匹配是否来自黑名单

User Image Object

用户图片对象

Field	Type	Description
`entities[].age`	string	Estimated age
`entities[].bbox`	array	Face bounding box `[x1, y1, x2, y2]`
`entities[].confidence`	float	Detection confidence (0-1)
`entities[].gender`	string	`"male"` or `"female"`
`best_angle`	integer	Rotation applied (0, 90, 180, 270)

字段	类型	说明
`entities[].age`	字符串	预估年龄
`entities[].bbox`	数组	人脸边界框 `[x1, y1, x2, y2]`
`entities[].confidence`	浮点数	检测置信度（0-1）
`entities[].gender`	字符串	`"male"` 或 `"female"`
`best_angle`	整数	应用的旋转角度（0、90、180、270）

Warning Tags

警告标签

Auto-Decline

自动拒绝

Tag	Description
`NO_FACE_DETECTED`	No face found in image
`FACE_IN_BLOCKLIST`	Face matches a blocklisted entry

标签	说明
`NO_FACE_DETECTED`	图片中未检测到人脸
`FACE_IN_BLOCKLIST`	人脸命中黑名单条目

Configurable

可配置

Tag	Description
`MULTIPLE_FACES_DETECTED`	Multiple faces detected — unclear which to use

Similarity threshold and allow multiple faces settings are configurable in Console.

Warning severity:

error

(→ Declined),

warning

(→ In Review),

information

(no effect).

标签	说明
`MULTIPLE_FACES_DETECTED`	检测到多张人脸 — 无法确定使用哪一张

相似度阈值和允许多张人脸设置可在控制台中配置。

警告级别：

error

（→ 拒绝）、

warning

（→ 待审核）、

information

（无影响）。

Common Workflows

常见工作流

Duplicate Account Detection

重复账户检测

1. During new user registration
2. POST /v3/face-search/ → {"user_image": selfie}
3. If total_matches == 0 → new unique user
   If matches found → check similarity_percentage:
     90%+ → likely duplicate, investigate matches[].vendor_data
     70-89% → possible match, flag for manual review

1. 在新用户注册时
2. 调用POST /v3/face-search/ → {"user_image": 自拍照}
3. 若total_matches == 0 → 新用户为唯一账户
   若存在匹配结果 → 检查similarity_percentage：
     90%+ → 大概率为重复账户，排查matches[].vendor_data
     70-89% → 可能匹配，标记为人工审核

Combined Verification + Dedup

验证+去重组合流程

1. POST /v3/passive-liveness/ → verify user is real
2. POST /v3/face-search/ → check for existing accounts
3. POST /v3/id-verification/ → verify identity document
4. POST /v3/face-match/ → compare selfie to document photo
5. All Approved → verified, unique, real user

Security: Match image URLs expire after 60 minutes. Store only
session_id
and
similarity_percentage
— minimize biometric data on your servers.

1. 调用POST /v3/passive-liveness/ → 验证用户为真人
2. 调用POST /v3/face-search/ → 检查是否存在已有账户
3. 调用POST /v3/id-verification/ → 验证身份证件
4. 调用POST /v3/face-match/ → 比对自拍照与证件照片
5. 全部通过 → 已验证、唯一且真实的用户

安全提示： 匹配图片URL会在60分钟后过期。仅存储
session_id
和
similarity_percentage
— 尽量减少在您服务器上存储的生物特征数据。

Utility Scripts

实用脚本

search_faces.py: Search for matching faces from the command line.

bash

undefined

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

bash

undefined

Requires: pip install requests

依赖：pip install requests

export DIDIT_API_KEY="your_api_key" python scripts/search_faces.py selfie.jpg python scripts/search_faces.py photo.png --rotate --vendor-data user-123

undefined

export DIDIT_API_KEY="your_api_key" python scripts/search_faces.py selfie.jpg python scripts/search_faces.py photo.png --rotate --vendor-data user-123

undefined