Age Detection API

How does age estimation from a photo work?

Age detection is a four-step pipeline. First, the API decodes the uploaded image and runs face detection to locate every face in the frame. Second, each detected face is normalised — cropped, aligned, and scaled — so the model sees a consistent input. Third, a model trained on a large, age-labelled face dataset predicts an age distribution from facial structure and skin-texture cues such as bone proportion, wrinkle patterns, and tonal gradients. Fourth, that distribution is reduced to a reported age range (a low and high bound) plus a confidence score, and returned for each face.

The API deliberately returns a range rather than a single number. Faces of the same chronological age vary widely, so a band like 19–27 is a more honest representation of model certainty than a precise "23". Treat the bounds as the operational signal: decisions should be made against the edge of the range nearest your threshold, not its midpoint. Pixicular's image analysis API exposes this as the first-class detect-age service — you do not have to reach for it through a generic face endpoint.

How accurate is photo age estimation?

Estimating age from a single still image is inherently approximate. On clear, well-lit, front-facing photos of a single subject, the predicted range typically lands within a few years of the true age. Accuracy is highest for children and young adults, where growth and ageing cues are strong and well-separated, and lower for middle and older ages, where the visible signal flattens and the natural spread of how people age widens the honest range.

Several factors degrade accuracy: low resolution and motion blur, harsh or low light, extreme head pose, partial occlusion (sunglasses, masks, hair), heavy beautification filters, and very small faces in the frame. Design for this. Near a legal threshold, widen your decision margin: treat a range that straddles the boundary as "uncertain" and escalate it rather than forcing a pass or block on a noisy midpoint. For population-level analytics the errors largely average out; for per-user gating they do not, which is why escalation paths matter.

Which image types are supported?

The age detection API accepts standard web image formats — JPEG, PNG, and WebP — sent as multipart form data. It is designed for photographs containing one or more clearly visible human faces. For the most reliable estimate, each face should be reasonably sharp, roughly front-facing, and a meaningful size within the frame.

• Good inputs: selfies, ID-style portraits, profile photos, and group photos with distinct, unoccluded faces.
• Weak inputs: tiny or blurred faces, extreme angles, heavy filters, masks or sunglasses, and non-photographic images such as illustrations or avatars.
• If no face is detected, the service returns an empty face list — handle that explicitly and prompt the user for a clearer photo rather than failing closed.

What is the JSON response format?

A request returns one JSON document with a key per requested service. For detect-age, the value is a list of faces; each face carries a normalised bounding box, an estimated ageRange with a low and high bound, and a confidence score. Group photos return one entry per detected face so you can gate on the youngest.

{
  "detect-age": {
    "faces": [
      {
        "boundingBox": { "x": 0.31, "y": 0.18, "width": 0.22, "height": 0.34 },
        "ageRange": { "low": 19, "high": 27 },
        "confidence": 0.91
      },
      {
        "boundingBox": { "x": 0.62, "y": 0.21, "width": 0.20, "height": 0.31 },
        "ageRange": { "low": 34, "high": 46 },
        "confidence": 0.87
      }
    ]
  },
  "meta": {
    "processingTimeMs": 412,
    "requestId": "req_8f2c1a9e"
  }
}

Field names, bounds behaviour, and exact confidence semantics are defined in the Pixicular API documentation. Note: Pixicular's AI-generated image detection service is currently disabled while accuracy is being improved. The detect-age service described here is live today.

Code: calling the age detection API

One request, one service. The image is uploaded once and the response is a single JSON document you parse for the age range.

curl -X POST https://api.pixicular.com/detect \
  -H "Authorization: Bearer $PIXICULAR_API_KEY" \
  -F "image=@./profile-photo.jpg" \
  -F "services=detect-age"

// Gate a sign-up flow on an estimated age range.
async function checkAgeGate(file: Blob, minimumAge: number) {
  const body = new FormData();
  body.append("image", file);
  body.append("services", "detect-age");

  const res = await fetch("https://api.pixicular.com/detect", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.PIXICULAR_API_KEY}` },
    body,
  });
  const result = await res.json();

  const faces = result["detect-age"]?.faces ?? [];
  if (faces.length === 0) return "no_face_retry";

  // Use the lower bound and a safety margin near the legal threshold.
  const youngest = Math.min(
    ...faces.map((f: { ageRange: { low: number } }) => f.ageRange.low),
  );
  const SAFETY_MARGIN = 3;

  if (youngest >= minimumAge + SAFETY_MARGIN) return "pass";
  if (youngest < minimumAge - SAFETY_MARGIN) return "block";
  return "escalate_to_id_check";
}

Supported use cases

Age estimation fits anywhere you need a fast, low-friction age signal without forcing every user through document verification. In each case the API supplies the range; your service owns the decision.

For stricter regulated contexts, pair estimation with a stronger check — see age verification for age-restricted platforms for how estimation feeds a gating decision, and image moderation for dating apps for combining age signals with content moderation on profile photos.

Age estimation, compliance, and data minimisation

Estimating age from a face is biometric processing under the GDPR and comparable regimes, which means you need a lawful basis and, in many cases, explicit consent, a data protection impact assessment, and a clear retention policy. The practical pattern is data minimisation: send the image, read the age range, make the decision, and discard the photo. Persist only what an audit genuinely requires — typically the decision and a coarse bucket, not the raw image or an exact predicted age tied to a user.

For children's-data regimes — COPPA in the US (under-13) and the GDPR's age-of-consent provisions for information society services (commonly 16, lowered to as low as 13 by some member states) — estimation is best used as a trigger: a likely under-threshold result routes the user into a parental-consent or restricted-experience flow rather than silently blocking them. This is general information, not legal advice — confirm your obligations with counsel and the API documentation before deploying age gating in a regulated jurisdiction.

Frequently asked questions