> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Face Analysis
> VU's Face Analysis API: compares two faces, scores selfie quality, and estimates pose, attributes and liveness in a single HTTP call.
The **Face Analysis** service is a facial-analysis toolbox behind a single endpoint. You send one or more images and declare, per image, which operations to run: 1:1 biometric comparison, capture-quality scoring, head-pose estimation, facial attributes, passive liveness, age and gender.
The central use case is **identity verification**: comparing a person's selfie against their document photo — or against a stored biometric vector — and getting a 0–100 similarity score. The other operations support that flow: capture quality decides whether to ask for another photo, and antispoofing decides whether the selfie came from a person who is actually present.
## The decision rule
This is the most important part of the integration. Write it in the positive:
```js theme={null}
// Confirming requires both conditions and the threshold. Anything else does NOT confirm.
if (status === 200 && body.biometric?.["0"]?.["1"] >= 70) {
samePerson(); // 70: threshold for the default methodology (vu_v4)
} else {
notConfirmed();
}
```
**Never confirm by exclusion.** There is no code that means “not the same person”: a no-match arrives with `200` and a low score. If your condition approves by exclusion, any unexpected response — a plain-text `500`, a missing block — turns into an approval.
Three contract details that break integrations:
1. **The matrix keys are strings**, not numbers: `biometric["0"]["1"]`. In typed languages, deserialize as a map from `string` to object.
2. **The 70 threshold is valid only for `vu_v4`**, the default methodology. The same two photos of the same person score 95 with `vu_v4`, 78 with `cosine` and 66 with `euclidean_l2` — a 66 that, read against the `vu_v4` threshold, would mean “different person”.
3. **`confidences` is a duplicate of `biometric`** kept for backwards compatibility. Do not read it; decide on `biometric`.
## Endpoints
| Method | Path | What it's for |
| - | - | - |
| `GET` | `/version` | Verify connectivity. Check the status code, not the body. Does not require the api-key. |
| `POST` | `/inference` | Run the requested operations on the submitted images. |
The base URL depends on the environment and is provided by VU along with your api-key. Examples below refer to it as `BASE_URL`.
## Authentication
Every call carries the `Api-Key` header with your environment's key.
```bash theme={null}
curl -X GET "$BASE_URL/version" \
-H "Api-Key: $VU_FACE_ANALYSIS_API_KEY"
```
The api-key belongs in your backend. Never embed it in a mobile app or front-end bundle — anyone can extract it from the binary or the JavaScript.
## A complete example
Comparing two faces — the selfie against the document photo:
```bash theme={null}
curl -X POST "$BASE_URL/inference" \
-H "Api-Key: $VU_FACE_ANALYSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"info": "onboarding-12345",
"images": ["/9j/4AAQSkZJRgABAQ...", "/9j/4AAQSkZJRgABAQ..."],
"operations": [["biometric"], ["biometric"]]
}'
```
A confirmation looks like this, trimmed to the fields that matter:
```json theme={null}
{
"id": "e0e9c259-ab66-4455-a330-c9a0d3b40567",
"info": "onboarding-12345",
"code": 200,
"message": "Operation end successfully",
"biometric": { "0": { "0": 100, "1": 93 }, "1": { "1": 100, "0": 93 } },
"benchmark": 200
}
```
`biometric["0"]["1"]` = 93 ≥ 70 ⇒ same person. The diagonal (`"0"` against `"0"`) is always 100; ignore it. `id` is the transaction identifier: always log it — it is the first thing support will ask for.
## The available operations
| Operation | What it returns |
| - | - |
| `biometric` | The 0–100 similarity matrix between every face in the call. **Runs by default if you omit `operations`.** |
| `faceFeatures` | 16 attributes scored 0–100: blur, eyeglasses, face mask, closed eyes, lighting… |
| `headPoseEstimation` | The pose in degrees: yaw (`leftRight`) and pitch (`upDown`). |
| `antiSpoofing` | The full response of the [Facial Antispoofing](/en/vucs/antispoofing-face/introduction) service, nested. |
| `gazeTrackingEstimation` | Pixel coordinates of both irises. |
| `facialAgeGender` | Estimated age and gender probability. Consistency signals, not registry data. |
| `steganography` | Verification of the steganographic signature of images generated by VU components. |
When you request `faceFeatures` **and** `headPoseEstimation` together, the service adds the aggregated quality verdict in `inferenceConfidence`: `high`, `medium` or `low`. The details are in [Responses](/en/vucs/face-analysis/responses).
## Environments
**The UAT environment may run ahead of production.** It also validates pre-release versions, so response times and scores can differ. Use it to certify your integration — the contract, the status codes, the error handling — not as a performance reference and not to compare scores image by image across environments.
## Next
Prepare the images, align `operations`, build the call, and validate before production.
The biometric matrix, the nested quality verdict, and the antispoofing inside the response.
Status codes, the plain-text 500s, and which errors are safe to retry.
## Related topics
- [ID Analysis](/en/vucs/id-analysis/introduction.md)
- [Interpreting responses](/en/vucs/face-analysis/responses.md)
- [VU Cloud Services](/en/vucs/introduction.md)
- [Integration guide](/en/vucs/face-analysis/integration.md)
- [Errors and diagnostics](/en/vucs/face-analysis/errors.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.