集成Didit Face Match独立API以比对两张面部图像。适用于用户需要比对面部、验证身份或实现生物识别的场景。
Didit Face Match API.是一项面向实际任务的技能,主要用于Overview. compare 两种面部图像以确定它们是否属于同一人.;Return a commonity country country (0-100).;
从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
比对两张人脸图像,判断是否属于同一人,并返回相似度得分(0–100)。
关键限制:
user_image 和 ref_image 均为必填项能力特性:相似度评分、年龄估计、性别检测、人脸边界框(bounding box)、可配置的拒绝阈值(decline threshold)、对非正向人脸的可选图像旋转支持。
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 调用完成创建:
POST https://apx.didit.me/auth/v2/programmatic/register/ 发送请求,请求体为 {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}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 技能。
POST https://verification.didit.me/v3/face-match/
| 请求头 | 值 | 是否必需 |
|---|---|---|
x-api-key |
您的 API 密钥 | 是 |
Content-Type |
multipart/form-data |
是 |
| 参数名 | 类型 | 是否必需 | 默认值 | 约束条件 | 说明 |
|---|---|---|---|---|---|
user_image |
file | 是 | — | JPEG/PNG/WebP/TIFF,最大 5MB | 待验证用户的面部图像 |
ref_image |
file | 是 | — | 同上 | 用于比对的参考图像 |
face_match_score_decline_threshold |
integer | 否 | 30 |
取值范围:0–100 | 低于该值的得分为“拒绝”状态 |
rotate_image |
boolean | 否 | false |
— | 尝试 0°/90°/180°/270° 旋转以定位正向人脸 |
save_api_request |
boolean | 否 | true |
— | 保存至商户控制台“人工核查”列表中 |
vendor_data |
string | 否 | — | — | 您用于会话追踪的自定义标识符 |
import requests
response = requests.post(
"https://verification.didit.me/v3/face-match/",
headers={"x-api-key": "YOUR_API_KEY"},
files={
"user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg"),
"ref_image": ("id_photo.jpg", open("id_photo.jpg", "rb"), "image/jpeg"),
},
data={"face_match_score_decline_threshold": "50"},
)
const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("ref_image", referenceFile);
formData.append("face_match_score_decline_threshold", "50");
const response = await fetch("https://verification.didit.me/v3/face-match/", {
method: "POST",
headers: { "x-api-key": "YOUR_API_KEY" },
body: formData,
});
{
"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"
}
| 状态 | 含义 | 建议操作 |
|---|---|---|
"Approved" |
得分 ≥ 阈值 | 人脸匹配成功 — 可继续后续流程 |
"Declined" |
得分 < 阈值,或未检测到人脸 | 检查 warnings 字段获取详情;可能需要质量更高的图像 |
"In Review" |
需人工审核 | 等待审核结果,或通过会话 API 主动查询 |
| HTTP 状态码 | 含义 | 建议操作 |
|---|---|---|
400 |
请求非法 | 检查文件格式、大小及参数合法性 |
401 |
API 密钥无效 | 确认 x-api-key 请求头是否正确设置 |
403 |
账户余额不足 | 前往 business.didit.me 充值 |
| 字段名 | 类型 | 说明 |
|---|---|---|
status |
string | "Approved"、"Declined" 或 "In Review" |
score |
integer | 0–100 的相似度得分(越高表示越相似);若未检测到人脸则为 null |
entities[].age |
float | 估算年龄 |
entities[].bbox |
array | 人脸边界框坐标 [x1, y1, x2, y2] |
entities[].confidence |
float | 人脸检测置信度(0–1) |
entities[].gender |
string | "male" 或 "female" |
best_angle |
integer | 使该人脸呈现最佳朝向所需的旋转角度(单位:度) |
warnings |
array | 警告对象数组,结构为 {risk, log_type, short_description, long_description} |
| 标签 | 说明 | 是否自动拒绝 |
|---|---|---|
NO_REFERENCE_IMAGE |
缺少参考图像或人脸图像 | 是 |
NO_FACE_DETECTED |
一张或两张图像中均未检测到人脸 | 是 |
LOW_FACE_MATCH_SIMILARITY |
得分低于阈值 — 存在身份不一致风险 | 可配置 |
安全最佳实践:仅存储
status和score字段;尽量避免在您自己的服务器上持久化生物特征图像数据。在工作流模式下返回的图像 URL 有效期为 60 分钟,过期后自动失效。
| 得分区间 | 解读 | 建议操作 |
|---|---|---|
| 90–100 | 极高置信度 — 极大概率是同一人 | 自动通过 |
| 70–89 | 高置信度 — 很可能是同一人 | 通过(默认阈值为 30) |
| 50–69 | 中等置信度 — 可能匹配 | 建议进入人工复核环节 |
| 30–49 | 低置信度 — 很可能不是同一人 | 按默认阈值被拒绝 |
| 0–29 | 极低置信度 — 基本可判定为不同人 | 拒绝 |
export DIDIT_API_KEY="your_api_key" python scripts/match_faces.py selfie.jpg id_photo.jpg python scripts/match_faces.py selfie.jpg id_photo.jpg --threshold 50 --rotate
相关专题
热门下载
相关下载
精品课程
共6课时 | 54.7万人学习
共89课时 | 134.3万人学习
共49课时 | 82.7万人学习
最新文章