Skip to main content
POST
/
v1
/
face
/
estimate-age
Estimate Age
curl --request POST \
  --url https://api.deepidv.com/v1/face/estimate-age
{
  "faceDetected": true,
  "estimatedAge": 34,
  "ageRange": { "low": 28, "high": 40 },
  "gender": "female",
  "genderConfidence": 0.97
}

POST /v1/face/estimate-age
Submit a single image containing a face. The response returns an age range, a single integer estimate within the range, and a gender estimate with confidence. Use this when you need to gate an experience by approximate age — for example, age-restricted product access — without requiring a full ID scan.

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key
Content-TypeYesmultipart/form-data or application/json

​
Body parameters

ParameterTypeRequiredDescription
imagebinary | stringYesThe image. For multipart, the file part. For JSON, a base64, base64url, or S3-key string.
See the overview for the shared image rules.

​
Example request

curl -X POST https://api.deepidv.com/v1/face/estimate-age \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@selfie.jpg"

​
Response

​
200 — Success

FieldTypeDescription
faceDetectedbooleanTrue when a face was detected
estimatedAgeintegerSingle age estimate (midpoint of the range). Omitted if no face
ageRangeobject{ low, high } integer age band. Omitted if no face
genderstringmale or female. Omitted if no face
genderConfidencenumber (0–1)Confidence of the gender classification. Omitted if no face

​
Error responses

StatusDescription
400Invalid body, unsupported image format, or image larger than 15 MB
401Missing or invalid x-api-key
402Insufficient token balance
403The supplied image S3 key is not readable by this organization
429Rate limit exceeded
500Unexpected server error — safe to retry with backoff
{
  "faceDetected": true,
  "estimatedAge": 34,
  "ageRange": { "low": 28, "high": 40 },
  "gender": "female",
  "genderConfidence": 0.97
}

​
Interpreting the range

The returned range is broad by design — Rekognition estimates an age band, not a single value. A common pattern is:
  • If ageRange.low >= your_minimum_age, accept immediately.
  • If ageRange.high < your_minimum_age, reject immediately.
  • Otherwise the user falls in the ambiguous band — fall back to a full ID-based verification via /v1/document/scan or /v1/identity/verify.
Age estimation is probabilistic and should not be used as a sole signal for regulated age checks (alcohol, tobacco, gambling). Combine it with an ID scan when compliance matters.