Age Prediction API Documentation

Overview

The API accepts JSON requests and analyzes the primary face in an image. Every successful response includes api_version; every failure uses the same structured error envelope.

Base URL: https://api.rate-my-photo.com. Contact sales before production use to discuss access and pricing.

Method	Path	Purpose
`POST`	`/age`	Estimate age; optionally return a boundary box, face crop, and face mesh.
`POST`	`/facemesh`	Return facial keypoints; optionally return frontalized keypoints and pose.

Quickstart

Send a JSON request with exactly one image source. This example uses raw base64 data and relies on the default age response fields.

curl -X POST https://api.rate-my-photo.com/age \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 1.1' \
  -d '{
    "face_image": "<base64-encoded-image>"
  }'

Example response

{
  "api_version": "1.1",
  "age": 25.42,
  "boundary_box": {
    "x": 113,
    "y": 89,
    "width": 142,
    "height": 180
  }
}

Image input

Both endpoints require exactly one of the following request fields:

Field	Type	Description
`face_image`	string	Raw base64 or a `data:image/...;base64,` data URI.
`face_image_url`	string	A public HTTP or HTTPS image URL. Private, loopback, link-local, and unreachable targets are refused.

Limits and preprocessing

Decoded image size must not exceed 15 MB.
Neither image dimension may exceed 4500 px.
If the longest side is above 1000 px, the image is downscaled to a maximum side of 1000 px with aspect ratio preserved.
For a combined request, age and face mesh analysis run on that same processed image.

Versioning

Set the optional X-API-Version request header. If the header is omitted, the API defaults to version 1.1. The effective version is echoed in the response header and JSON body.

X-API-Version: 1.1

An unsupported value returns HTTP 400 with error code UNSUPPORTED_VERSION.

Age estimation

POST /age

Estimates the apparent age of the primary face.

Parameter	Type	Default	Effect
`return_boundary_box`	boolean	`true`	Include `x`, `y`, `width`, and `height`.
`return_face_base64`	boolean	`false`	Include a base64-encoded crop of the detected face.
`return_facemesh`	boolean	`false`	Also run face mesh analysis and enable its output parameters.

The age field is numeric. The boundary box and face crop appear only when requested and available.

Face mesh

POST /facemesh

Returns 478 normalized three-dimensional landmarks for the primary face.

Parameter	Type	Default	Effect
`return_keypoints`	boolean	`true`	Include the 478 `x`, `y`, and `z` keypoints.
`return_frontalized_keypoints`	boolean	`false`	Include 478 frontalized keypoints.
`return_pose`	boolean	`false`	Include head-pose measurements such as yaw, pitch, and roll.

Example request

{
  "face_image_url": "https://example.com/portrait.jpg",
  "return_frontalized_keypoints": true,
  "return_pose": true
}

Abbreviated response

{
  "api_version": "1.1",
  "keypoints": [
    { "x": 0.47999, "y": 0.58708, "z": -0.04268 }
  ],
  "frontalized_keypoints": [
    { "x": 0.48012, "y": 0.58191, "z": -0.03924 }
  ],
  "pose": {
    "yaw": 1.2,
    "pitch": -2.4,
    "roll": 0.8,
    "off_frontal_deg": 2.8,
    "frontal_deviation": 0.03
  }
}

The arrays shown above are abbreviated. A full keypoint response contains 478 entries. The face mesh endpoint does not expose a boundary box.

Age + face mesh

There is no separate /both route. Use POST /age, set return_facemesh to true, and add any face mesh output flags you need.

{
  "face_image": "<base64-encoded-image>",
  "return_boundary_box": true,
  "return_facemesh": true,
  "return_frontalized_keypoints": true,
  "return_pose": true
}

Face mesh fields are nested under facemesh in the age response:

{
  "api_version": "1.1",
  "age": 25.42,
  "boundary_box": { "x": 113, "y": 89, "width": 142, "height": 180 },
  "facemesh": {
    "keypoints": [ ... ],
    "frontalized_keypoints": [ ... ],
    "pose": { ... }
  }
}

Error handling

Errors use an HTTP status appropriate to the failure and a stable machine-readable code.

{
  "api_version": "1.1",
  "error": {
    "code": "NO_FACE_DETECTED",
    "message": "No face was detected in the supplied image."
  }
}

Status	Code	Meaning
400	`VALIDATION_ERROR`	Missing or conflicting image sources, invalid fields, or an invalid URL.
400	`UNSUPPORTED_VERSION`	The requested API version is not supported.
413	`IMAGE_TOO_LARGE`	The decoded image exceeds 15 MB.
413	`IMAGE_DIMENSIONS_TOO_LARGE`	An image side exceeds 4500 px.
422	`INVALID_IMAGE`	The image or base64 data cannot be decoded.
422	`NO_FACE_DETECTED`	No usable face was found.
422	`IMAGE_URL_UNREACHABLE`	The URL failed or resolved to a refused address.
502	`UPSTREAM_ERROR`	An analysis service returned an unexpected response.
504	`UPSTREAM_TIMEOUT`	An analysis service did not respond in time.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

Planning a production integration?

Tell us about your use case, expected traffic, and required response fields.

Contact sales