Face Analysis

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:

// 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:

The matrix keys are strings, not numbers: biometric["0"]["1"]. In typed languages, deserialize as a map from string to object.
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”.
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.

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:

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:

{
  "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 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.

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.

Integration

Prepare the images, align operations, build the call, and validate before production.

Responses

The biometric matrix, the nested quality verdict, and the antispoofing inside the response.

Errors

Status codes, the plain-text 500s, and which errors are safe to retry.

Start here

ID Analysis

Facial Antispoofing

Connection Fingerprint

Face Analysis

The decision rule

Endpoints

Authentication

A complete example

The available operations

Environments

Next

Integration

Responses

Errors

​The decision rule

​Endpoints

​Authentication

​A complete example

​The available operations

​Environments

​Next

Integration

Responses

Errors

The decision rule

Endpoints

Authentication

A complete example

The available operations

Environments

Next