didit-protocol Didit Age Estimation API
Overview
Estimates a person's age from a facial image using deep learning. Also performs a passive liveness check to prevent spoofing.
Key constraints:
- Supported formats: JPEG, PNG, WebP, TIFF
- Maximum file size: 5MB
- Image must contain one clearly visible face
- Accuracy: MAE ±3.5 years overall; ±1.5 years for under-18
Capabilities: Age estimation with confidence scoring, gender estimation, passive liveness detection, configurable age thresholds, per-country age restrictions, adaptive mode with ID verification fallback for borderline cases.
Liveness methods (workflow mode):
| Method | Security | Best For |
|---|---|---|
ACTIVE_3D (Action + Flash) |
Highest | Banking, government, healthcare |
FLASHING (3D Flash) |
High | Financial services, identity verification |
PASSIVE (single-frame CNN) |
Standard | Low-friction consumer apps |
API Reference: https://docs.didit.me/standalone-apis/age-estimation Feature Guide: https://docs.didit.me/core-technology/age-estimation/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/age-estimation/
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 | — | Facial image (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 Manual Checks |
vendor_data |
string | No | — | Your identifier for session tracking |
Example
import requests
response = requests.post(
"https://verification.didit.me/v3/age-estimation/",
headers={"x-api-key": "YOUR_API_KEY"},
files={"user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg")},
data={"vendor_data": "user-123"},
)
print(response.json())
const formData = new FormData();
formData.append("user_image", selfieFile);
const response = await fetch("https://verification.didit.me/v3/age-estimation/", {
method: "POST",
headers: { "x-api-key": "YOUR_API_KEY" },
body: formData,
});
Response (200 OK)
{
"request_id": "a1b2c3d4-...",
"liveness": {
"status": "Approved",
"method": "PASSIVE",
"score": 89.92,
"age_estimation": 24.3,
"reference_image": "https://example.com/reference.jpg",
"video_url": null,
"warnings": []
},
"created_at": "2025-05-01T13:11:07.977806Z"
}
Status Values & Handling
| Status | Meaning | Action |
|---|---|---|
"Approved" |
Age verified above threshold, liveness passed | Proceed with your flow |
"Declined" |
Age below minimum or liveness failed | Check warnings for specifics |
"In Review" |
Borderline case, needs review | Trigger ID verification fallback or manual 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 |
Response Field Reference
| Field | Type | Description |
|---|---|---|
status |
string | "Approved", "Declined", "In Review", "Not Finished" |
method |
string | "ACTIVE_3D", "FLASHING", or "PASSIVE" |
score |
float | 0-100 liveness confidence score |
age_estimation |
float | Estimated age in years (e.g. 24.3). null if no face |
reference_image |
string | Temporary URL (expires 4 hours) |
video_url |
string | Temporary URL for active liveness video. null for passive |
warnings |
array | {risk, log_type, short_description, long_description} |
Accuracy by Age Range
| Age Range | MAE (years) | Confidence |
|---|---|---|
| Under 18 | 1.5 | High |
| 18-25 | 2.8 | High |
| 26-40 | 3.2 | High |
| 41-60 | 3.9 | Medium-High |
| 60+ | 4.5 | Medium |
Warning Tags
Auto-Decline
| Tag | Description |
|---|---|
NO_FACE_DETECTED |
No face found in image |
LIVENESS_FACE_ATTACK |
Spoofing attempt detected |
FACE_IN_BLOCKLIST |
Face matches a blocklist entry |
Configurable (Decline / Review / Approve)
| Tag | Description |
|---|---|
AGE_BELOW_MINIMUM |
Estimated age below configured minimum |
AGE_NOT_DETECTED |
Unable to estimate age (image quality, lighting) |
LOW_LIVENESS_SCORE |
Liveness score below threshold |
POSSIBLE_DUPLICATED_FACE |
Significant similarity with previously verified face |
Warning severity: error (→ Declined), warning (→ In Review), information (no effect).
Common Workflows
Basic Age Gate
1. Capture user selfie
2. POST /v3/age-estimation/ → {"user_image": selfie}
3. Check liveness.age_estimation >= your_minimum_age
4. If "Approved" → user meets age requirement
If "Declined" → check warnings for AGE_BELOW_MINIMUM or liveness failure
Adaptive Age Estimation (Workflow Mode)
Build a workflow with an AGE_ESTIMATION feature (optionally followed by OCR for the ID verification fallback) so borderline ages trigger automatic ID verification.
1. POST /v3/workflows/ → {"workflow_label": "Adaptive Age", "features": [{"feature": "AGE_ESTIMATION"}, {"feature": "OCR"}]}
2. POST /v3/session/ → create session with the workflow_id from step 1
3. User takes selfie → system estimates age
4. Clear pass (well above threshold) → Approved instantly
Clear fail (well below threshold) → Declined
Borderline case → automatic ID verification fallback
5. If ID fallback triggered: per-country age restrictions apply
Per-Country Age Restrictions
Configure in Console per issuing country:
| Country | Min Age | Overrides |
|---|---|---|
| USA | 18 | Mississippi: 21, Alabama: 19 |
| KOR | 19 | — |
| GBR | 18 | — |
| ARE | 21 | — |
Use "Apply age of majority" button in Console to auto-populate defaults.
Utility Scripts
estimate_age.py: Estimate age from a facial image via the command line.
# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/estimate_age.py selfie.jpg
python scripts/estimate_age.py photo.png --threshold 21 --vendor-data user-123