Face Analysis

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:

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

Las claves de la matriz son cadenas, no números: biometric["0"]["1"]. En lenguajes con tipos, deserialice como mapa de string a objeto.
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».
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.

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:

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:

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

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

Integración

Prepare las imágenes, alinee operations, arme la llamada y valide antes de producción.

Respuestas

La matriz biométrica, el veredicto de calidad anidado y el antispoofing dentro de la respuesta.

Errores

Códigos, los 500 en texto plano y cuáles errores se reintentan.

Empezar aquí

ID Analysis

Antispoofing Facial

Connection Fingerprint

Face Analysis

La regla de decisión

Endpoints

Autenticación

Un ejemplo completo

Las operaciones disponibles

Ambientes

Continuar

Integración

Respuestas

Errores

​La regla de decisión

​Endpoints

​Autenticación

​Un ejemplo completo

​Las operaciones disponibles

​Ambientes

​Continuar

Integración

Respuestas

Errores

La regla de decisión

Endpoints

Autenticación

Un ejemplo completo

Las operaciones disponibles

Ambientes

Continuar