didit-face-match

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Didit Face Match API

Overview

概述

Compares two facial images to determine if they belong to the same person. Returns a similarity score (0-100).

Key constraints:

Supported formats: JPEG, PNG, WebP, TIFF
Maximum file size: 5MB per image
If multiple faces in an image, the largest face is used for comparison
Both
```
user_image
```
and
```
ref_image
```
are required

Capabilities: Similarity scoring, age estimation, gender detection, face bounding boxes, configurable decline threshold, optional image rotation for non-upright faces.

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

对比两张人脸图像，判断是否属于同一人，返回0-100范围的相似度评分。

核心限制：

支持格式：JPEG、PNG、WebP、TIFF
单张图片最大大小：5MB
若图片中存在多张人脸，将选取面积最大的人脸进行比对
```
user_image
```
和
```
ref_image
```
两个参数均为必填项

功能特性： 相似度评分、年龄估算、性别检测、人脸 bounding box、可配置拒绝阈值、可选自动旋转非正向人脸图片。

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

Endpoint

接口地址

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

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

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	Constraints	Description
`user_image`	file	Yes	—	JPEG/PNG/WebP/TIFF, max 5MB	User's face image to verify
`ref_image`	file	Yes	—	Same as above	Reference image to compare against
`face_match_score_decline_threshold`	integer	No	`30`	0-100	Scores below this = Declined
`rotate_image`	boolean	No	`false`	—	Try 0/90/180/270 degree rotations to find upright face
`save_api_request`	boolean	No	`true`	—	Save in Business Console Manual Checks
`vendor_data`	string	No	—	—	Your identifier for session tracking

参数	类型	是否必填	默认值	约束	描述
`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	否	—	—	自定义标识，用于会话追踪

Example

示例代码

python

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"},
)

typescript

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,
});

python

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"},
)

typescript

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,
});

Response (200 OK)

响应（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"
}

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"
}

Status Values & Handling

状态值说明与处理

Status	Meaning	Action
`"Approved"`	Score >= threshold	Faces match — proceed
`"Declined"`	Score < threshold or no face	Check `warnings` for details. May need better image
`"In Review"`	Needs manual review	Wait for review or retrieve via session API

状态	含义	处理建议
`"Approved"`	评分≥阈值	人脸匹配，可继续后续流程
`"Declined"`	评分<阈值或未检测到人脸	查看 `warnings` 获取详情，可能需要重新上传更高质量的图片
`"In Review"`	需要人工审核	等待审核结果，或通过会话接口查询审核状态

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

响应字段说明

Field	Type	Description
`status`	string	`"Approved"` , `"Declined"` , `"In Review"`
`score`	integer	0-100 similarity score (higher = more similar). `null` if no face found
`entities[].age`	float	Estimated age
`entities[].bbox`	array	Face bounding box `[x1, y1, x2, y2]`
`entities[].confidence`	float	Face detection confidence (0-1)
`entities[].gender`	string	`"male"` or `"female"`
`best_angle`	integer	Best rotation angle for the face
`warnings`	array	`{risk, log_type, short_description, long_description}`

字段	类型	描述
`status`	string	取值为 `"Approved"` 、 `"Declined"` 、 `"In Review"`
`score`	integer	0-100的相似度评分，分值越高相似度越高；未检测到人脸时为 `null`
`entities[].age`	float	估算年龄
`entities[].bbox`	array	人脸 bounding box，格式为 `[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}`

Warning Tags

警告标签说明

Tag	Description	Auto-Decline
`NO_REFERENCE_IMAGE`	Reference or face image missing	Yes
`NO_FACE_DETECTED`	No face detected in one or both images	Yes
`LOW_FACE_MATCH_SIMILARITY`	Score below threshold — potential identity mismatch	Configurable

Security best practice: Only store the status and score. Minimize biometric image data on your servers. Image URLs (in workflow mode) expire after 60 minutes.

标签	描述	是否自动拒绝
`NO_REFERENCE_IMAGE`	参考图片或人脸图片缺失	是
`NO_FACE_DETECTED`	一张或两张图片中未检测到人脸	是
`LOW_FACE_MATCH_SIMILARITY`	评分低于阈值，可能身份不匹配	可配置

安全最佳实践： 仅存储状态和评分即可，尽量减少在你的服务器上存储生物特征图像数据。工作流模式下的图片URL有效期仅为60分钟。

Score Interpretation

评分解读

Score Range	Interpretation	Action
90-100	Very high confidence — same person	Auto-approve
70-89	High confidence — likely same person	Approve (default threshold 30)
50-69	Moderate — possible match	Consider manual review
30-49	Low — likely different people	Declined at default threshold
0-29	Very low — different people	Declined

评分范围	含义	处理建议
90-100	置信度极高，为同一人	自动通过
70-89	置信度高，大概率为同一人	通过（默认阈值为30）
50-69	置信度中等，可能匹配	建议人工审核
30-49	置信度低，大概率不是同一人	默认阈值下直接拒绝
0-29	置信度极低，不是同一人	直接拒绝

Utility Scripts

工具脚本

bash

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

bash

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