Didit Biometric Age Estimation

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:

1. Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}
2. Check email for a 6-character OTP code
3. 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).

---

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 60 min) | | 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)

Uses workflow_type: "adaptive_age_verification" — creates a session where borderline ages trigger automatic ID verification fallback.

1. POST /v3/workflows/ → {"workflow_type": "adaptive_age_verification", "is_liveness_enabled": true, "is_age_restrictions_enabled": true}
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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: didit-protocol
• Source: didit-protocol/skills
• License: MIT

Install and usage instructions live in the source repository linked above.