> ## 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.

# Report di stima dell'età: schema JSON e campi

> Analizza i report di Stima dell'età di Didit: età stimata, vitalità passiva, qualità del viso, soglie e avvisi. Pay-per-call da $0.10.

Il report di Stima dell'età rileva un'età stimata dal modello (in anni) per il volto più grande rilevato in un'immagine, combinata con un controllo di vitalità passiva che conferma che il soggetto sia una persona reale anziché una foto, uno schermo o una maschera. I due controlli vengono sempre eseguiti insieme — Stima dell'età non restituisce mai un'età senza un punteggio di vitalità.

Questa pagina documenta la struttura JSON restituita da entrambi i percorsi di chiamata: l'endpoint standalone `POST /v3/age-estimation/` e il campo integrato `age_estimation` nei report di vitalità del workflow.

![Report di Stima dell'età di Didit con età stimata, punteggio di vitalità passiva e metriche di qualità del volto](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)

## Panoramica

Stima dell'età prevede due modalità di consegna:

* **API standalone.** `POST /v3/age-estimation/` accetta un'unica immagine del volto (`user_image`) e restituisce l'età stimata e il punteggio di vitalità passiva in modo sincrono. Consulta il [riferimento API standalone di Stima dell'età](https://docs.didit.me/it/standalone-apis/age-estimation.md).
* **Integrato in un workflow.** Ogni report di vitalità del workflow include l'età stimata nel campo `age_estimation` — il valore viene sempre ricavato dal volto più grande rilevato. Le soglie di età vengono *applicate* (generando avvisi sull'età) solo nei flussi di stima dell'età: workflow di verifica dell'età adattivi o nodi di workflow `AGE_ESTIMATION`.

Ogni report contiene:

* Lo `status` complessivo (`Approved`, `Declined`).
* Il `method` di vitalità (sempre `PASSIVE` nell'API standalone; `ACTIVE_3D` / `FLASHING` / `PASSIVE` nei workflow).
* Uno `score` di vitalità (0–100; più è alto, maggiore è la probabilità che il soggetto sia in vita; `null` viene trattato come `0` per i controlli di soglia).
* Il valore `age_estimation` stimato in anni (float — ad esempio `27.33`; `null` quando non è stato possibile stimare l'età del volto).
* Solo standalone: un oggetto `user_image` con un array `entities[]` (una voce per ciascun volto rilevato — `age`, `bbox`, `confidence`, `gender`) e l'orientamento `best_angle`.
* Solo workflow: `reference_image`, `video_url`, `matches[]` e le metriche di qualità della vitalità passiva `face_quality` (0–100%) e `face_luminance` (0–100%). La risposta standalone **non** include questi campi.
* Un array `warnings[]` — eventi di rischio generati durante il controllo (vedi [Avvisi di Stima dell'età](https://docs.didit.me/it/core-technology/age-estimation/warnings-age-estimation.md)).

La decisione standalone è `Declined` ogni volta che `warnings` non è vuoto — `Approved` richiede un array vuoto. Gli avvisi scattano quando:

* Lo `score` di vitalità è pari o inferiore a `face_liveness_score_decline_threshold` (valore predefinito `30`) — `LOW_LIVENESS_SCORE`.
* L'età stimata è inferiore a `age_estimation_decline_threshold` (valore predefinito `18`) — `AGE_BELOW_MINIMUM`. Imposta la soglia su `0` per disabilitare il controllo dell'età.
* Non viene rilevato alcun volto (`NO_FACE_DETECTED`) oppure non è stato possibile stimare l'età del volto (`AGE_NOT_DETECTED`).
* Il modello di vitalità segnala un attacco di presentazione (`LIVENESS_FACE_ATTACK`).

## Dove compare nelle risposte dell'API

### API standalone — `POST /v3/age-estimation/`

La risposta standalone racchiude il risultato all'interno di un unico oggetto `age_estimation` di primo livello, insieme a `request_id` e ai campi `vendor_data` / `metadata` riproposti nella risposta. Quando `save_api_request=true` (impostazione predefinita), `request_id` è l'ID della sessione persistente e il risultato può essere recuperato in seguito anche dall'endpoint decisionale; quando è `false`, è un UUID di correlazione monouso.

```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"
}
```

### Decisione del workflow — `GET /v3/session/{session_id}/decision/`

In una sessione di workflow, l'età stimata è **incorporata all'interno del report di vitalità — non esiste un array separato per la stima dell'età**. L'endpoint decisionale V3 restituisce i report di vitalità nell'array con chiave al plurale **`liveness_checks`** (`ReducedSessionV3DecisionSerializer.get_liveness_checks`), e ciascuna voce contiene un float `age_estimation` — l'età stimata del volto più grande rilevato — oppure `null` se non è stata calcolata alcuna età (`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,
      "...": "..."
    }
  ]
}
```

Leggi l'età da `liveness_checks[].age_estimation`. Le chiamate standalone persistite (`save_api_request=true`) compaiono allo stesso modo sull'endpoint decisionale, con `features` che contiene `AGE_ESTIMATION`.

## Schema

Lo schema canonico campo per campo si trova nella pagina [Modelli di dati](https://docs.didit.me/it/reference/data-models.md#stima-dell’età). La struttura della risposta standalone è documentata da `AgeEstimationResponseSerializer` e assemblata in `AgeEstimationAPIView`; il valore del workflow è generato da `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[];
}
```

### Valori di status

Le stringhe di stato provengono dall'enum condiviso degli stati delle funzionalità (vedi [Enum degli stati](https://docs.didit.me/it/reference/data-models.md#riferimento-agli-enum-di-stato)). L'endpoint standalone restituisce esclusivamente:

| Status | Significato |
| - | - |
| `Approved` | Nessun avviso attivato — il soggetto è in vita e l'età stimata rispetta la soglia configurata. |
| `Declined` | Almeno un avviso attivato — punteggio di vitalità basso, età inferiore alla soglia, nessun volto, nessuna età o attacco. |

Nelle sessioni di workflow, il controllo di vitalità può anche risolversi in `In Review` quando un rischio configurabile genera un'azione di revisione (ad esempio `POSSIBLE_DUPLICATED_FACE`). Consulta il [riferimento all'enum degli stati](https://docs.didit.me/it/reference/data-models.md#riferimento-agli-enum-di-stato).

## Esempi

### Approved — standalone, soggetto adulto

```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"
}
```

### Declined — standalone, età stimata inferiore alla soglia

```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"
}
```

### Approved — incorporato in un report di vitalità del workflow

```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 di sicurezza

Tutti gli URL di immagini e video restituiti nella risposta sono link pre-firmati con una finestra temporale di validità limitata. Trattali come riferimenti di breve durata: non condividerli pubblicamente e chiama nuovamente l'endpoint decisionale per aggiornare gli URL scaduti. Come buona prassi, memorizza dal tuo lato solo lo stato di verifica e i valori di affidabilità, anziché i file multimediali biometrici sottostanti.

## Risorse correlate

* [Panoramica di Stima dell'età](https://docs.didit.me/it/core-technology/age-estimation/overview.md) — comportamento della funzionalità, prezzi, logica decisionale.
* [Avvisi di Stima dell'età](https://docs.didit.me/it/core-technology/age-estimation/warnings-age-estimation.md) — tutti i codici di rischio e i trigger di rifiuto.
* [Riferimento API standalone](https://docs.didit.me/it/standalone-apis/age-estimation.md) — richiesta e risposta per `POST /v3/age-estimation/`.
* [Modelli di dati — stima dell'età](https://docs.didit.me/it/reference/data-models.md#stima-dell’età) — schema canonico campo per campo.
* [Vitalità passiva](https://docs.didit.me/it/core-technology/liveness/overview.md) — il modello di vitalità condiviso utilizzato nelle risposte della stima dell'età.


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