Didit 人脸搜索 API (1:N)

概述

将参考人脸与所有先前已批准的验证会话进行比较，以检测重复账户和黑名单中的人脸。返回带有相似度得分的排名匹配结果。

关键限制：

• - 支持的格式：JPEG、PNG、WebP、TIFF
• 最大文件大小：5MB
• 与您应用中所有已批准的会话进行比较
• 黑名单匹配会导致自动拒绝

相似度得分指南：

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

身份验证

所有请求都需要 x-api-key 标头。从 Didit 业务控制台 → API 和 Webhooks 获取您的密钥，或通过编程方式注册（见下文）。

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

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

1. 1. 注册： POST https://apx.didit.me/auth/v2/programmatic/register/，请求体为 {email: you@gmail.com, password: MyStr0ng!Pass}
2. 检查邮箱 获取 6 位 OTP 验证码
3. 验证： 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/ 请求体为 {amountindollars: 50} 获取 Stripe 结账链接。

完整的平台管理（工作流、会话、用户、计费）请参阅 didit-verification-management 技能。

端点

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

请求头

请求参数（multipart/form-data）

示例

python
import requests

response = requests.post(
https://verification.didit.me/v3/face-search/,
headers={x-api-key: YOURAPIKEY},
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: YOURAPIKEY },
body: formData,
});

响应（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
},
matchimageurl: 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: []
}
}

状态值及处理

错误响应

响应字段参考

匹配对象

用户图像对象

警告标签

自动拒绝

可配置

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

警告严重级别：error（→ 已拒绝）、warning（→ 审核中）、information（无影响）。

常见工作流

重复账户检测

1. 1. 新用户注册期间
2. POST /v3/face-search/ → {userimage: 自拍照}
3. 如果 totalmatches == 0 → 新的唯一用户

组合验证 + 去重

1. 1. POST /v3/passive-liveness/ → 验证用户是真人
2. POST /v3/face-search/ → 检查现有账户
3. POST /v3/id-verification/ → 验证身份证明文件
4. POST /v3/face-match/ → 比较自拍照与证件照片