> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Interpreta la respuesta de estimación de edad de Didit: edad estimada, liveness pasivo, calidad facial, umbrales y advertencias. Desde $0.10.

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](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/age-estimation-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=f0ae767c591e55866d0cf5496291e17b)

## 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](https://docs.didit.me/es/standalone-apis/age-estimation.md).
* **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](https://docs.didit.me/es/core-technology/age-estimation/warnings-age-estimation.md)).

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.

```json theme={null}
{
  "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`).

```json theme={null}
{
  "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](https://docs.didit.me/es/reference/data-models.md#estimación-de-edad). La estructura de la respuesta independiente está documentada por `AgeEstimationResponseSerializer` y se construye en `AgeEstimationAPIView`; el valor del flujo lo genera `LivenessV3Serializer`.

```typescript theme={null}
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](https://docs.didit.me/es/reference/data-models.md#referencia-de-los-valores-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](https://docs.didit.me/es/reference/data-models.md#referencia-de-los-valores-de-estado).

## Ejemplos

### Aprobado: independiente, persona adulta

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](https://docs.didit.me/es/core-technology/age-estimation/overview.md): comportamiento de la función, precios y lógica de decisión.
* [Advertencias de Estimación de edad](https://docs.didit.me/es/core-technology/age-estimation/warnings-age-estimation.md): todos los códigos de riesgo y disparadores de rechazo.
* [Referencia de la API independiente](https://docs.didit.me/es/standalone-apis/age-estimation.md): solicitud y respuesta de `POST /v3/age-estimation/`.
* [Modelos de datos: estimación de edad](https://docs.didit.me/es/reference/data-models.md#estimación-de-edad): esquema canónico campo por campo.
* [Prueba de vida pasiva](https://docs.didit.me/es/core-technology/liveness/overview.md): el modelo de prueba de vida compartido que se usa en las respuestas de estimación de edad.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.