Skip to main content

Age by Image API

Upload an image to detect people and faces and predict an age with a confidence percentage for each detection.

Base URL​

https://api.genderrecognition.com

Endpoint​

POST /v1/image-gender/api/age

Headers​

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

Body​

FieldTypeRequiredDescription
filefileYesJPEG, PNG, WebP, BMP, or GIF image. Maximum size: 10 MB.

Example​

curl -X POST "https://api.genderrecognition.com/v1/image-gender/api/age" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

Successful response​

{
  "success": true,
  "detections": [
    {
      "age": 27.4,
      "probability": 99
    },
    {
      "age": 41.2,
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

Response fields​

FieldTypeDescription
successbooleantrue when the image was processed successfully.
detectionsarrayOne entry for each detected face with an age prediction.
detections[].agenumberPredicted age for the detection. Can include a decimal.
detections[].probabilityintegerConfidence percentage from 0 to 100. See note below.
remainingRequestsintegerAPI requests remaining after this successful request is deducted.

probability is the model's confidence in the gender classification for that detection, reused as the reported confidence value — the model does not produce a separate confidence score for the age estimate itself. A high probability reflects how sure the model is about the person's gender, not about the accuracy of age.

Only detections where the model produced a confident gender classification are included. A face with an ambiguous or unmatched gender prediction is omitted from detections even if a person or face was visually detected, so detections can be shorter than the number of faces in the image.

No detections​

Processing can succeed without finding a face with a confident prediction. This still consumes one request:

{
  "success": true,
  "detections": [],
  "remainingRequests": 2999
}

Error responses​

Missing API key — 401 Unauthorized​

{
  "error": "API key is required"
}

Invalid API key — 404 Not Found​

{
  "error": "Invalid API key"
}

Authentication service error — 500 Internal Server Error​

{
  "error": "Internal server error"
}

Missing file — 400 Bad Request​

The multipart field must be named file.

{
  "error": "No file uploaded"
}

Unexpected multipart field — 400 Bad Request​

This response is returned when the uploaded file uses a field name other than file, or when more than one file is sent using the single-file field.

{
  "error": "Unexpected field"
}

Invalid file type — 400 Bad Request​

{
  "error": "Invalid file type. Allowed formats: JPEG, PNG, WEBP, BMP, GIF"
}

File too large — 400 Bad Request​

{
  "error": "File too large"
}

Image cannot be decoded — 400 Bad Request​

{
  "error": "Could not decode image"
}

The prediction service can also return another 400 validation message when the uploaded image is invalid. The response uses the same { "error": "..." } shape.

Prediction service size rejection — 413 Payload Too Large​

{
  "error": "Uploaded file exceeds the 10MB size limit"
}

Quota exceeded — 400 Bad Request​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Paid plans use the same response structure with plan-specific limits, reset dates, and upgrade guidance.

Quota changed during processing — 400 Bad Request​

Quota is checked before prediction and deducted after successful processing. If another concurrent request consumes the remaining quota between those operations, the deduction can return:

{
  "error": "Insufficient remaining requests. Required: 1, Available: 0"
}

Processing failed — 500 Internal Server Error​

{
  "error": "Image age prediction failed"
}

If the upstream prediction service returns a more specific internal error, its message can be returned in the error field with the same response shape.

Notes​

  • Send exactly one image using the multipart field named file.
  • A request is deducted only after the prediction service returns successfully.
  • age can be a decimal value; probability is a whole-number percentage, not a decimal between 0 and 1.
  • probability reflects gender-classification confidence, not confidence in the age estimate — there is no dedicated age-confidence score.
  • An empty detections array is a successful result, not an error.
  • Predictions are model estimates and should not be treated as verified identity attributes.