Informe de estimación de edad: esquema JSON y campos

El informe de Estimación de edad recoge una edad predicha por el modelo (en años) para el rostro más grande detectado en una imagen, junto con una comprobación pasiva de prueba de vida que confirma que el sujeto es una persona real y no una foto, una pantalla o una máscara. Las dos comprobaciones siempre se ejecutan juntas: la Estimación de edad nunca devuelve una edad sin una puntuación de prueba de vida. Esta página documenta la estructura JSON que devuelven las dos vías de llamada: el endpoint independiente POST /v3/age-estimation/ y el campo age_estimation incluido en los informes de prueba de vida de los flujos.

Informe de estimación de edad de Didit con la edad predicha, la puntuación de prueba de vida pasiva y las métricas de calidad del rostro

Descripción general

La Estimación de edad tiene dos modos de entrega:

API independiente. POST /v3/age-estimation/ acepta una sola imagen de rostro (user_image) y devuelve de forma síncrona la edad predicha y la puntuación de prueba de vida pasiva. Consulta la referencia de la API independiente de Estimación de edad.
Integrada en un flujo de verificación (workflow). Todo informe de prueba de vida de un flujo incluye la edad predicha en age_estimation; el valor siempre se obtiene del rostro más grande detectado. Los umbrales de edad solo se aplican (generando advertencias de edad) en los flujos de estimación de edad: flujos de verificación de edad adaptativa o nodos AGE_ESTIMATION del flujo.

Cada informe contiene:

El status general (Approved, Declined).
El method de prueba de vida (siempre PASSIVE en la API independiente; ACTIVE_3D / FLASHING / PASSIVE en los flujos).
Una score de prueba de vida (de 0 a 100; cuanto más alta, mayor es la confianza en que la persona está viva; null se trata como 0 en las comprobaciones de umbral).
La age_estimation predicha en años (float, por ejemplo 27.33; null cuando no se pudo estimar la edad de ningún rostro).
Solo en la API independiente: un objeto user_image con un array entities[] (una entrada por cada rostro detectado: age, bbox, confidence, gender) y la orientación best_angle.
Solo en los flujos: reference_image, video_url, matches[] y las métricas de calidad de la prueba de vida pasiva face_quality (de 0 a 100%) y face_luminance (de 0 a 100%). La respuesta de la API independiente no incluye estos campos.
Un array warnings[]: eventos de riesgo emitidos durante la comprobación (consulta las advertencias de Estimación de edad).

La decisión de la API independiente es Declined siempre que warnings no esté vacío; Approved requiere un array vacío. Las advertencias se generan cuando:

La score de prueba de vida es igual o inferior a face_liveness_score_decline_threshold (por defecto 30): LOW_LIVENESS_SCORE.
La edad predicha es inferior a age_estimation_decline_threshold (por defecto 18): AGE_BELOW_MINIMUM. Establece el umbral en 0 para desactivar la comprobación de edad.
No se detecta ningún rostro (NO_FACE_DETECTED) o no se pudo estimar la edad de ningún rostro (AGE_NOT_DETECTED).
El modelo de prueba de vida detecta un ataque de presentación (LIVENESS_FACE_ATTACK).

Dónde aparece en las respuestas de la API

API independiente: `POST /v3/age-estimation/`

La respuesta independiente agrupa el resultado en un único objeto age_estimation de nivel superior, junto con request_id y los valores vendor_data / metadata devueltos tal como se enviaron. Cuando save_api_request=true (el valor por defecto), request_id es el id de la sesión guardada y el resultado también se puede obtener más tarde desde el endpoint de decisión; cuando es false, es un UUID de correlación de un solo uso.

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": { "entities": [ /* ... */ ], "best_angle": 0 },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}

Decisión del flujo: `GET /v3/session/{session_id}/decision/`

En una sesión de flujo, la edad predicha está incluida dentro del informe de prueba de vida: no hay un array de estimación de edad independiente. El endpoint de decisión V3 devuelve los informes de prueba de vida bajo la clave de array en plural liveness_checks (ReducedSessionV3DecisionSerializer.get_liveness_checks), y cada entrada incluye un float age_estimation (la edad estimada del rostro detectado de mayor tamaño) o null si no se calculó ninguna edad (LivenessV2Serializer.get_age_estimation).

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "features": ["AGE_ESTIMATION"],
  "liveness_checks": [
    {
      "node_id": "feature_age_estimation_1",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "age_estimation": 24.3,
      "...": "..."
    }
  ]
}

Lee la edad en liveness_checks[].age_estimation. Las llamadas independientes guardadas (save_api_request=true) aparecen de la misma forma en el endpoint de decisión, con features que contiene AGE_ESTIMATION.

Esquema

El esquema canónico campo por campo está en la página de Modelos de datos. La estructura de la respuesta independiente está documentada por AgeEstimationResponseSerializer y se construye en AgeEstimationAPIView; el valor del flujo lo genera LivenessV3Serializer.

interface AgeEstimationStandalone {
  request_id: string;                  // Session id when save_api_request=true
  age_estimation: {
    status: "Approved" | "Declined";
    method: "PASSIVE";
    score: number | null;              // Passive liveness score (0-100); null counts as 0
    age_estimation: number | null;     // Predicted age in years of the largest face (float)
    user_image: {
      entities: Array<{
        age: number;                   // Estimated age of this face
        bbox: [number, number, number, number];  // [x_min, y_min, x_max, y_max]
        confidence: number;            // Face-detection confidence (0-1)
        gender: "male" | "female";
      }>;
      best_angle: number | null;       // Rotation (0/90/180/270) with best detection
    };
    warnings: Warning[];
  };
  vendor_data: string | null;          // Echoed from the request
  metadata: object | null;             // Echoed from the request
  created_at: string;                  // ISO 8601
}

interface WorkflowLivenessWithAge {
  node_id: string | null;
  status: "Approved" | "Declined" | "In Review";
  method: "ACTIVE_3D" | "FLASHING" | "PASSIVE";
  score: number | null;                // Liveness score (0-100)
  reference_image: string;             // Presigned URL
  video_url: string | null;            // Presigned URL (active liveness only)
  age_estimation: number | null;       // Predicted age in years (float)
  face_quality: number | null;         // 0-100% (passive liveness only)
  face_luminance: number | null;       // 0-100% (passive liveness only)
  warnings: Warning[];
  matches: FaceMatch[];
}

Valores de estado

Las cadenas de estado provienen del enum compartido de estados de funciones (consulta Enums de estado). El endpoint independiente solo devuelve:

Estado	Significado
`Approved`	No se generó ninguna advertencia: la persona está viva y la edad predicha cumple el umbral configurado.
`Declined`	Se generó al menos una advertencia: puntuación de prueba de vida baja, edad inferior al umbral, no se detecta ningún rostro, no se calcula ninguna edad o se detecta un ataque.

En las sesiones de flujo, la prueba de vida también puede resolverse como In Review cuando se activa un riesgo configurable con una acción de revisión (por ejemplo, POSSIBLE_DUPLICATED_FACE). Consulta la referencia de enums de estado.

Ejemplos

Aprobado: independiente, persona adulta

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": {
      "entities": [
        { "age": 27.33, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}

Rechazado: independiente, edad predicha inferior al umbral

{
  "request_id": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
  "age_estimation": {
    "status": "Declined",
    "method": "PASSIVE",
    "score": 92.0,
    "age_estimation": 15.8,
    "user_image": {
      "entities": [
        { "age": 15.8, "bbox": [55, 60, 110, 110], "confidence": 0.81, "gender": "female" }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "AGE_BELOW_MINIMUM",
        "feature": "LIVENESS",
        "additional_data": null,
        "log_type": "error",
        "short_description": "Age below minimum",
        "long_description": "The age of the face is below the minimum age threshold for the application."
      }
    ]
  },
  "vendor_data": "user-456",
  "metadata": null,
  "created_at": "2026-06-12T02:26:40.118332+00:00"
}

Aprobado: incluido en un informe de prueba de vida de un flujo de trabajo

{
  "node_id": "feature_age_estimation_1",
  "status": "Approved",
  "method": "PASSIVE",
  "score": 89.92,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 24.3,
  "matches": [],
  "face_quality": 87.5,
  "face_luminance": 54.12,
  "warnings": []
}

Nota de seguridad

Todas las URL de imágenes y videos que se devuelven en la respuesta son enlaces prefirmados con un período de validez limitado. Trátalas como referencias de corta duración: no las compartas públicamente y vuelve a llamar al endpoint de decisión para renovar las URL expiradas. Como buena práctica, guarda en tu sistema solo el estado de la verificación y los puntuaciones de confianza, no el material biométrico subyacente.

Relacionado

Descripción general de Estimación de edad: comportamiento de la función, precios y lógica de decisión.
Advertencias de Estimación de edad: todos los códigos de riesgo y disparadores de rechazo.
Referencia de la API independiente: solicitud y respuesta de POST /v3/age-estimation/.
Modelos de datos: estimación de edad: esquema canónico campo por campo.
Prueba de vida pasiva: el modelo de prueba de vida compartido que se usa en las respuestas de estimación de edad.

Autenticación

Verificación

Monitorización

Plataforma

Informe de estimación de edad: esquema JSON y campos

Descripción general

Dónde aparece en las respuestas de la API

API independiente: `POST /v3/age-estimation/`

Decisión del flujo: `GET /v3/session/{session_id}/decision/`

Esquema

Valores de estado

Ejemplos

Aprobado: independiente, persona adulta

Rechazado: independiente, edad predicha inferior al umbral

Aprobado: incluido en un informe de prueba de vida de un flujo de trabajo

Nota de seguridad

Relacionado

​Descripción general

​Dónde aparece en las respuestas de la API

​API independiente: POST /v3/age-estimation/

​Decisión del flujo: GET /v3/session/{session_id}/decision/

​Esquema

​Valores de estado

​Ejemplos

​Aprobado: independiente, persona adulta

​Rechazado: independiente, edad predicha inferior al umbral

​Aprobado: incluido en un informe de prueba de vida de un flujo de trabajo

​Nota de seguridad

​Relacionado

Descripción general

Dónde aparece en las respuestas de la API

API independiente: `POST /v3/age-estimation/`

Decisión del flujo: `GET /v3/session/{session_id}/decision/`

Esquema

Valores de estado

Ejemplos

Aprobado: independiente, persona adulta

Rechazado: independiente, edad predicha inferior al umbral

Aprobado: incluido en un informe de prueba de vida de un flujo de trabajo

Nota de seguridad

Relacionado