Face Services
Face attributes
Return demographic and quality attributes from a detected face.
POST /api/v2/faces:detect and the index endpoints accept an
attributes parameter that controls how much extra information is
returned about each detected face:
| Value | What you get |
|---|---|
none | Bounding box only. Fastest. |
default | Bounding box plus core quality signals. |
all | Every attribute below. Slightly higher latency. |
Passing an unsupported value returns invalid_attributes (400) — see
Error codes.
Attributes returned with all
Each attribute ships with a value and, where relevant, a confidence between 0 and 1. Confidences are direct signals of how sure the detector is; treat them as "how much to trust this particular field" not "how much to trust the overall result."
| Attribute | Type | How to read it |
|---|---|---|
pose | { roll, yaw, pitch } in degrees | Near-zero on all three axes is front-facing. Absolute values above ~30° mean the face is turned or tilted enough to hurt comparison accuracy. |
brightness | Value 0–1 | Perceptual brightness of the face region. Around 0.4–0.7 is ideal. Low values mean the photo is too dark; high values mean it's blown out. |
sharpness | Value 0–1 | Focus / motion-blur estimate. Higher is sharper. Treat below ~0.3 as suspect. |
eyes_open | Boolean + confidence | true means both eyes look open. Use the confidence to decide how strictly to enforce it. |
mouth_closed | Boolean + confidence | true for a neutral expression. Useful when you want an ICAO-like reference image. |
eyeglasses | Boolean + confidence | Whether the face appears to be wearing glasses. Handy for flagging state changes between onboarding and re-auth. |
Practical use
- Gate the compare. Before calling
faces:compare, reject images with lowsharpnessor extremeposeand ask the user to retake. A compare against a blurry or heavily angled face will produce a legitimately low similarity score and frustrate everyone. - Pick the best reference. When you have several shots, keep the
one with the best combined
sharpness, centredpose, and mid-rangebrightness. - Audit gracefully. Log attribute values alongside similarity scores; they're the first thing to check when a match result looks wrong.
Related: Face Services overview · ICAO photo.