didit-face-search
Integrate Didit Face Search standalone API to perform 1:N facial search against all previously verified sessions. Use when the user wants to detect duplicate accounts, search for matching faces, check if a face already exists in the system, prevent duplicate registrations, search against blocklist, or implement facial deduplication using Didit. Returns ranked matches with similarity percentages.
- License 许可
- MIT
- 最近更新
- 2026-06-07
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- didit-face-search
- version
- 1.0.0
- metadata
- { "openclaw": { "emoji": "🔍", "homepage": "https://docs.didit.me", "requires": { "env": [ "DIDIT_API_KEY" ] }, "primaryEnv": "DIDIT_API_KEY" } }
- description
- Integrate Didit Face Search standalone API to perform 1:N facial search against all previously verified sessions. Use when the user wants to detect duplicate accounts, search for matching faces, check if a face already exists in the system, prevent duplicate registrations, search against blocklist, or implement facial deduplication using Didit. Returns ranked matches with similarity percentages.
03 SKILL.md 正文
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
Authentication
All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).
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 includesapi_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).
Endpoint
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 |
Request Parameters (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 |
Example
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())
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)
{
"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 |
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 |
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 |
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) |
Warning Tags
Auto-Decline
| Tag | Description |
|---|---|
NO_FACE_DETECTED |
No face found in image |
FACE_IN_BLOCKLIST |
Face matches a blocklisted entry |
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).
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
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_idandsimilarity_percentage— minimize biometric data on your servers.
Utility Scripts
search_faces.py: Search for matching faces from the command line.
# Requires: 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
04 同仓库更多 Skills
crowd-prompting
A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.
ceaser
Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).
ceaser-send
Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.
dilemm-ai
Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).
moldium
Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.
arxiv-paper-reviews
Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.