{"skill":{"slug":"didit-biometric-age-estimation","displayName":"Didit Biometric Age Estimation","summary":"Estimates a person's age from a facial image via the Didit standalone API. Use when implementing age gating, checking if someone is over 18 or 21, performing...","description":"---\nname: didit-biometric-age-estimation\ndescription: >\n  Estimates a person's age from a facial image via the Didit standalone API. Use when\n  implementing age gating, checking if someone is over 18 or 21, performing age verification\n  for compliance, or detecting underage users. Includes passive liveness check. Supports\n  configurable thresholds, adaptive fallback to ID verification, and per-country restrictions.\nversion: 1.0.0\nmetadata:\n  openclaw:\n    requires:\n      env:\n        - DIDIT_API_KEY\n    primaryEnv: DIDIT_API_KEY\n    emoji: \"🎂\"\n    homepage: https://docs.didit.me\n---\n\n# Didit Age Estimation API\n\n## Overview\n\nEstimates a person's age from a facial image using deep learning. Also performs a passive liveness check to prevent spoofing.\n\n**Key constraints:**\n- Supported formats: **JPEG, PNG, WebP, TIFF**\n- Maximum file size: **5MB**\n- Image must contain **one clearly visible face**\n- Accuracy: MAE ±3.5 years overall; ±1.5 years for under-18\n\n**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.\n\n**Liveness methods (workflow mode):**\n\n| Method | Security | Best For |\n|---|---|---|\n| `ACTIVE_3D` (Action + Flash) | Highest | Banking, government, healthcare |\n| `FLASHING` (3D Flash) | High | Financial services, identity verification |\n| `PASSIVE` (single-frame CNN) | Standard | Low-friction consumer apps |\n\n**API Reference:** https://docs.didit.me/standalone-apis/age-estimation\n**Feature Guide:** https://docs.didit.me/core-technology/age-estimation/overview\n\n---\n\n## Authentication\n\nAll requests require `x-api-key` header. Get your key from [Didit Business Console](https://business.didit.me) → API & Webhooks, or via programmatic registration (see below).\n\n## Getting Started (No Account Yet?)\n\nIf you don't have a Didit API key, create one in 2 API calls:\n\n1. **Register:** `POST https://apx.didit.me/auth/v2/programmatic/register/` with `{\"email\": \"you@gmail.com\", \"password\": \"MyStr0ng!Pass\"}`\n2. **Check email** for a 6-character OTP code\n3. **Verify:** `POST https://apx.didit.me/auth/v2/programmatic/verify-email/` with `{\"email\": \"you@gmail.com\", \"code\": \"A3K9F2\"}` → response includes `api_key`\n\n**To add credits:** `GET /v3/billing/balance/` to check, `POST /v3/billing/top-up/` with `{\"amount_in_dollars\": 50}` for a Stripe checkout link.\n\nSee the **didit-verification-management** skill for full platform management (workflows, sessions, users, billing).\n\n---\n\n## Endpoint\n\n```\nPOST https://verification.didit.me/v3/age-estimation/\n```\n\n### Headers\n\n| Header | Value | Required |\n|---|---|---|\n| `x-api-key` | Your API key | **Yes** |\n| `Content-Type` | `multipart/form-data` | **Yes** |\n\n### Request Parameters (multipart/form-data)\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `user_image` | file | **Yes** | — | Facial image (JPEG/PNG/WebP/TIFF, max 5MB) |\n| `rotate_image` | boolean | No | `false` | Try 0/90/180/270 rotations for non-upright faces |\n| `save_api_request` | boolean | No | `true` | Save in Business Console Manual Checks |\n| `vendor_data` | string | No | — | Your identifier for session tracking |\n\n### Example\n\n```python\nimport requests\n\nresponse = requests.post(\n    \"https://verification.didit.me/v3/age-estimation/\",\n    headers={\"x-api-key\": \"YOUR_API_KEY\"},\n    files={\"user_image\": (\"selfie.jpg\", open(\"selfie.jpg\", \"rb\"), \"image/jpeg\")},\n    data={\"vendor_data\": \"user-123\"},\n)\nprint(response.json())\n```\n\n```typescript\nconst formData = new FormData();\nformData.append(\"user_image\", selfieFile);\n\nconst response = await fetch(\"https://verification.didit.me/v3/age-estimation/\", {\n  method: \"POST\",\n  headers: { \"x-api-key\": \"YOUR_API_KEY\" },\n  body: formData,\n});\n```\n\n### Response (200 OK)\n\n```json\n{\n  \"request_id\": \"a1b2c3d4-...\",\n  \"liveness\": {\n    \"status\": \"Approved\",\n    \"method\": \"PASSIVE\",\n    \"score\": 89.92,\n    \"age_estimation\": 24.3,\n    \"reference_image\": \"https://example.com/reference.jpg\",\n    \"video_url\": null,\n    \"warnings\": []\n  },\n  \"created_at\": \"2025-05-01T13:11:07.977806Z\"\n}\n```\n\n### Status Values & Handling\n\n| Status | Meaning | Action |\n|---|---|---|\n| `\"Approved\"` | Age verified above threshold, liveness passed | Proceed with your flow |\n| `\"Declined\"` | Age below minimum or liveness failed | Check `warnings` for specifics |\n| `\"In Review\"` | Borderline case, needs review | Trigger ID verification fallback or manual review |\n\n### Error Responses\n\n| Code | Meaning | Action |\n|---|---|---|\n| `400` | Invalid request | Check file format, size, parameters |\n| `401` | Invalid API key | Verify `x-api-key` header |\n| `403` | Insufficient credits | Top up at business.didit.me |\n\n---\n\n## Response Field Reference\n\n| Field | Type | Description |\n|---|---|---|\n| `status` | string | `\"Approved\"`, `\"Declined\"`, `\"In Review\"`, `\"Not Finished\"` |\n| `method` | string | `\"ACTIVE_3D\"`, `\"FLASHING\"`, or `\"PASSIVE\"` |\n| `score` | float | 0-100 liveness confidence score |\n| `age_estimation` | float | Estimated age in years (e.g. `24.3`). `null` if no face |\n| `reference_image` | string | Temporary URL (expires 60 min) |\n| `video_url` | string | Temporary URL for active liveness video. `null` for passive |\n| `warnings` | array | `{risk, log_type, short_description, long_description}` |\n\n### Accuracy by Age Range\n\n| Age Range | MAE (years) | Confidence |\n|---|---|---|\n| Under 18 | 1.5 | High |\n| 18-25 | 2.8 | High |\n| 26-40 | 3.2 | High |\n| 41-60 | 3.9 | Medium-High |\n| 60+ | 4.5 | Medium |\n\n---\n\n## Warning Tags\n\n### Auto-Decline\n\n| Tag | Description |\n|---|---|\n| `NO_FACE_DETECTED` | No face found in image |\n| `LIVENESS_FACE_ATTACK` | Spoofing attempt detected |\n| `FACE_IN_BLOCKLIST` | Face matches a blocklist entry |\n\n### Configurable (Decline / Review / Approve)\n\n| Tag | Description |\n|---|---|\n| `AGE_BELOW_MINIMUM` | Estimated age below configured minimum |\n| `AGE_NOT_DETECTED` | Unable to estimate age (image quality, lighting) |\n| `LOW_LIVENESS_SCORE` | Liveness score below threshold |\n| `POSSIBLE_DUPLICATED_FACE` | Significant similarity with previously verified face |\n\nWarning severity: `error` (→ Declined), `warning` (→ In Review), `information` (no effect).\n\n---\n\n## Common Workflows\n\n### Basic Age Gate\n\n```\n1. Capture user selfie\n2. POST /v3/age-estimation/ → {\"user_image\": selfie}\n3. Check liveness.age_estimation >= your_minimum_age\n4. If \"Approved\" → user meets age requirement\n   If \"Declined\" → check warnings for AGE_BELOW_MINIMUM or liveness failure\n```\n\n### Adaptive Age Estimation (Workflow Mode)\n\nUses `workflow_type: \"adaptive_age_verification\"` — creates a session where borderline ages trigger automatic ID verification fallback.\n\n```\n1. POST /v3/workflows/ → {\"workflow_type\": \"adaptive_age_verification\", \"is_liveness_enabled\": true, \"is_age_restrictions_enabled\": true}\n2. POST /v3/session/ → create session with the workflow_id from step 1\n3. User takes selfie → system estimates age\n4. Clear pass (well above threshold) → Approved instantly\n   Clear fail (well below threshold) → Declined\n   Borderline case → automatic ID verification fallback\n5. If ID fallback triggered: per-country age restrictions apply\n```\n\n### Per-Country Age Restrictions\n\nConfigure in Console per issuing country:\n\n| Country | Min Age | Overrides |\n|---|---|---|\n| USA | 18 | Mississippi: 21, Alabama: 19 |\n| KOR | 19 | — |\n| GBR | 18 | — |\n| ARE | 21 | — |\n\n> Use \"Apply age of majority\" button in Console to auto-populate defaults.\n\n---\n\n## Utility Scripts\n\n**estimate_age.py**: Estimate age from a facial image via the command line.\n\n```bash\n# Requires: pip install requests\nexport DIDIT_API_KEY=\"your_api_key\"\npython scripts/estimate_age.py selfie.jpg\npython scripts/estimate_age.py photo.png --threshold 21 --vendor-data user-123\n```\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":543,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1772514870875,"updatedAt":1778491695332},"latestVersion":{"version":"1.0.0","createdAt":1772514870875,"changelog":"Estimate age from facial images with passive liveness. Replaces didit-age-estimation","license":null},"metadata":{"setup":[{"key":"DIDIT_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"rosasalberto","userId":"s17fenh76mn5y28mwva6bcmn0h8858fw","displayName":"Didit","image":"https://avatars.githubusercontent.com/u/47662054?v=4"},"moderation":null}