Didit 人脸匹配 API

概述

比较两张人脸图像，判断是否属于同一个人。返回相似度评分（0-100）。

关键限制：

• - 支持的格式：JPEG、PNG、WebP、TIFF
• 最大文件大小：每张图片 5MB
• 如果图片中有多张人脸，使用最大的人脸进行比较
• userimage 和 refimage 均为必填项

功能： 相似度评分、年龄估计、性别检测、人脸边界框、可配置拒绝阈值、非正面人脸的可选图像旋转。

API 参考： https://docs.didit.me/standalone-apis/face-match
功能指南： https://docs.didit.me/core-technology/face-match/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-match/

请求头

请求参数（multipart/form-data）

示例

python
import requests

response = requests.post(
https://verification.didit.me/v3/face-match/,
headers={x-api-key: YOURAPIKEY},
files={
user_image: (selfie.jpg, open(selfie.jpg, rb), image/jpeg),
refimage: (idphoto.jpg, open(id_photo.jpg, rb), image/jpeg),
},
data={facematchscoredeclinethreshold: 50},
)

typescript
const formData = new FormData();
formData.append(user_image, selfieFile);
formData.append(ref_image, referenceFile);
formData.append(facematchscoredeclinethreshold, 50);

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

响应（200 OK）

json
{
request_id: a1b2c3d4-...,
face_match: {
status: Approved,
score: 80,
user_image: {
entities: [
{age: 27.63, bbox: [40, 40, 100, 100], confidence: 0.717, gender: male}
],
best_angle: 0
},
ref_image: {
entities: [
{age: 22.16, bbox: [156, 234, 679, 898], confidence: 0.717, gender: male}
],
best_angle: 0
},
warnings: []
},
created_at: 2025-05-01T13:11:07.977806Z
}

状态值及处理

错误响应

响应字段参考

警告标签

安全最佳实践： 仅存储状态和分数。尽量减少服务器上的生物特征图像数据。图像 URL（在工作流模式下）60 分钟后过期。

分数解读

实用脚本

bash
export DIDITAPIKEY=yourapikey

python scripts/matchfaces.py selfie.jpg idphoto.jpg
python scripts/matchfaces.py selfie.jpg idphoto.jpg --threshold 50 --rotate