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

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

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à.
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à).

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.

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

{
  "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. La struttura della risposta standalone è documentata da AgeEstimationResponseSerializer e assemblata in AgeEstimationAPIView; il valore del workflow è generato da 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[];
}

Valori di status

Le stringhe di stato provengono dall’enum condiviso degli stati delle funzionalità (vedi Enum degli stati). 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.

Esempi

Approved — standalone, soggetto adulto

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

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

{
  "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à — comportamento della funzionalità, prezzi, logica decisionale.
Avvisi di Stima dell’età — tutti i codici di rischio e i trigger di rifiuto.
Riferimento API standalone — richiesta e risposta per POST /v3/age-estimation/.
Modelli di dati — stima dell’età — schema canonico campo per campo.
Vitalità passiva — il modello di vitalità condiviso utilizzato nelle risposte della stima dell’età.

Autenticazione

Verifica

Monitoraggio

Piattaforma

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

Panoramica

Dove compare nelle risposte dell’API

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

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

Schema

Valori di status

Esempi

Approved — standalone, soggetto adulto

Declined — standalone, età stimata inferiore alla soglia

Approved — incorporato in un report di vitalità del workflow

Nota di sicurezza

Risorse correlate

​Panoramica

​Dove compare nelle risposte dell’API

​API standalone — POST /v3/age-estimation/

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

​Schema

​Valori di status

​Esempi

​Approved — standalone, soggetto adulto

​Declined — standalone, età stimata inferiore alla soglia

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

​Nota di sicurezza

​Risorse correlate

Panoramica

Dove compare nelle risposte dell’API

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

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

Schema

Valori di status

Esempi

Approved — standalone, soggetto adulto

Declined — standalone, età stimata inferiore alla soglia

Approved — incorporato in un report di vitalità del workflow

Nota di sicurezza

Risorse correlate