> ## 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
> API de Face Analysis de VU: compara dos rostros, evalúa la calidad de una selfie y estima pose, atributos y prueba de vida con una sola llamada HTTP.
El servicio de **Face Analysis** es una caja de herramientas de análisis facial detrás de un único endpoint. Usted envía una o más imágenes y declara, imagen por imagen, qué operaciones quiere correr: comparación biométrica 1:1, evaluación de calidad de la captura, estimación de pose, atributos faciales, prueba de vida pasiva, edad y género.
El caso de uso central es la **verificación de identidad**: comparar la selfie de una persona contra la foto de su documento —o contra un vector biométrico guardado— y obtener un puntaje de similitud de 0 a 100. Las demás operaciones acompañan ese flujo: la calidad de captura decide si vale la pena pedir otra foto, y el antispoofing decide si la selfie es de una persona presente.
## La regla de decisión
Esta es la parte más importante de la integración. Escríbala en positivo:
```js theme={null}
// Confirmar exige las dos condiciones y el umbral. Cualquier otra cosa NO confirma.
if (status === 200 && body.biometric?.["0"]?.["1"] >= 70) {
mismaPersona(); // 70: umbral para la metodología por defecto (vu_v4)
} else {
noConfirmada();
}
```
**No confirme por descarte.** No existe un código que signifique «no es la misma persona»: el no-match llega con `200` y un puntaje bajo. Si su condición aprueba por descarte, cualquier respuesta inesperada —un `500` en texto plano, un bloque ausente— se convierte en una aprobación.
Tres detalles del contrato que rompen integraciones:
1. **Las claves de la matriz son cadenas**, no números: `biometric["0"]["1"]`. En lenguajes con tipos, deserialice como mapa de `string` a objeto.
2. **El umbral 70 vale solo para `vu_v4`**, la metodología por defecto. Las mismas dos fotos de la misma persona puntúan 95 con `vu_v4`, 78 con `cosine` y 66 con `euclidean_l2` — un 66 que con el umbral de `vu_v4` se leería como «persona distinta».
3. **`confidences` es un duplicado de `biometric`** que existe por compatibilidad con integraciones antiguas. No lo lea; decida sobre `biometric`.
## Endpoints
| Método | Ruta | Para qué sirve |
| - | - | - |
| `GET` | `/version` | Verificar conectividad. Evalúe el código de estado, no el cuerpo. No exige api-key. |
| `POST` | `/inference` | Correr las operaciones pedidas sobre las imágenes enviadas. |
La URL base depende del ambiente y se la entrega VU junto con su api-key. En los ejemplos aparece como `BASE_URL`.
## Autenticación
Cada llamada lleva la cabecera `Api-Key` con la clave de su ambiente.
```bash theme={null}
curl -X GET "$BASE_URL/version" \
-H "Api-Key: $VU_FACE_ANALYSIS_API_KEY"
```
La api-key vive en su backend. Nunca la incruste en una app móvil ni en el front-end: cualquiera puede extraerla del binario o del bundle.
## Un ejemplo completo
Comparación de dos rostros — la selfie contra la foto del documento:
```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"]]
}'
```
Una confirmación se ve así, recortada a los campos que importan:
```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 ⇒ misma persona. La diagonal (`"0"` contra `"0"`) siempre vale 100; ignórela. `id` es el identificador de la transacción: registrelo siempre, es lo primero que le va a pedir soporte.
## Las operaciones disponibles
| Operación | Qué devuelve |
| - | - |
| `biometric` | La matriz de similitud 0–100 entre todos los rostros de la llamada. **Se ejecuta por defecto si omite `operations`.** |
| `faceFeatures` | 16 atributos 0–100: nitidez, anteojos, mascarilla, ojos cerrados, iluminación… |
| `headPoseEstimation` | La pose en grados: guiñada (`leftRight`) y cabeceo (`upDown`). |
| `antiSpoofing` | La respuesta completa del servicio de [Antispoofing Facial](/vucs/antispoofing-facial/introduccion), anidada. |
| `gazeTrackingEstimation` | Coordenadas de ambos iris en píxeles. |
| `facialAgeGender` | Edad estimada y probabilidad de género. Señales de consistencia, no datos registrales. |
| `steganography` | Verificación de la firma esteganográfica de imágenes generadas por componentes VU. |
Cuando pide `faceFeatures` **y** `headPoseEstimation` juntas, el servicio agrega el veredicto agregado de calidad en `inferenceConfidence`: `high`, `medium` o `low`. Los detalles están en [Respuestas](/vucs/face-analysis/respuestas).
## Ambientes
**Homologación puede ir adelantada respecto de producción.** UAT también valida versiones preproductivas, así que puede diferir en tiempos de respuesta y en los puntajes. Úselo para certificar su integración —el contrato, los códigos, el manejo de errores—, no como referencia de performance ni para comparar puntajes imagen por imagen entre ambientes.
## Continuar
Prepare las imágenes, alinee `operations`, arme la llamada y valide antes de producción.
La matriz biométrica, el veredicto de calidad anidado y el antispoofing dentro de la respuesta.
Códigos, los `500` en texto plano y cuáles errores se reintentan.
## Related topics
- [ID Analysis](/vucs/id-analysis/introduccion.md)
- [Interpretación de respuestas](/vucs/face-analysis/respuestas.md)
- [Errores y diagnóstico](/vucs/face-analysis/errores.md)
- [Guía de integración](/vucs/face-analysis/integracion.md)
- [VU Cloud Services](/vucs/introduccion.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.