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

# Rapport d'estimation de l'âge : schéma JSON et champs

> Explorez les réponses d'estimation de l'âge de Didit : âge estimé, score du vivant, métriques et seuils de refus. Dès $0.10 par appel.

Le rapport d'Estimation de l'âge recueille un âge prédit par le modèle (en années) pour le plus grand visage détecté dans une image, combiné à un contrôle passif de détection du vivant qui confirme que le sujet est une personne réelle plutôt qu'une photo, un écran ou un masque. Les deux vérifications s'exécutent toujours ensemble — l'Estimation de l'âge ne renvoie jamais d'âge sans score de détection du vivant.

Cette page documente la structure JSON renvoyée par les deux modes d'appel : l'endpoint autonome `POST /v3/age-estimation/` et le champ `age_estimation` intégré dans les rapports de détection du vivant de workflow.

![Rapport d'estimation de l'âge Didit avec âge prédit, score de détection passive du vivant et métriques de qualité du visage](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)

## Présentation

L'Estimation de l'âge dispose de deux modes de livraison :

* **API autonome.** `POST /v3/age-estimation/` accepte une seule image de visage (`user_image`) et renvoie de manière synchrone l'âge prédit et le score de détection passive du vivant. Consultez la [référence de l'API autonome d'Estimation de l'âge](https://docs.didit.me/fr/standalone-apis/age-estimation.md).
* **Intégrée dans un workflow.** Chaque rapport de détection du vivant de workflow contient l'âge prédit sous `age_estimation` — la valeur est toujours renseignée à partir du plus grand visage détecté. Les seuils d'âge ne sont *appliqués* (déclenchant des avertissements d'âge) que sur les flux d'estimation de l'âge : les workflows de vérification adaptative de l'âge ou les nœuds de workflow `AGE_ESTIMATION`.

Chaque rapport contient :

* Le `status` global (`Approved`, `Declined`).
* La `method` de détection du vivant (toujours `PASSIVE` sur l'API autonome ; `ACTIVE_3D` / `FLASHING` / `PASSIVE` dans les workflows).
* Un `score` de détection du vivant (0–100 ; plus il est élevé, plus la confiance dans le fait que le sujet est vivant est élevée ; `null` est traité comme `0` pour les vérifications de seuil).
* L'`age_estimation` prédit en années (nombre à virgule flottante — par exemple `27.33` ; `null` si aucun âge n'a pu être estimé pour le visage).
* Mode autonome uniquement : un objet `user_image` contenant un tableau `entities[]` (une entrée par visage détecté — `age`, `bbox`, `confidence`, `gender`) et l'orientation `best_angle`.
* Workflow uniquement : `reference_image`, `video_url`, `matches[]`, ainsi que les métriques de qualité de détection passive du vivant `face_quality` (0–100%) et `face_luminance` (0–100%). La réponse autonome n'inclut **pas** ces champs.
* Un tableau `warnings[]` — les événements de risque émis pendant la vérification (consultez les [avertissements de l'Estimation de l'âge](https://docs.didit.me/fr/core-technology/age-estimation/warnings-age-estimation.md)).

La décision en mode autonome est `Declined` dès lors que `warnings` n'est pas vide — `Approved` nécessite un tableau vide. Des avertissements se déclenchent lorsque :

* Le `score` de détection du vivant est inférieur ou égal à `face_liveness_score_decline_threshold` (par défaut `30`) — `LOW_LIVENESS_SCORE`.
* L'âge prédit est inférieur à `age_estimation_decline_threshold` (par défaut `18`) — `AGE_BELOW_MINIMUM`. Définissez le seuil sur `0` pour désactiver la vérification de l'âge.
* Aucun visage n'est détecté (`NO_FACE_DETECTED`) ou aucun âge n'a pu être estimé pour le visage (`AGE_NOT_DETECTED`).
* Le modèle de détection du vivant signale une attaque par présentation (`LIVENESS_FACE_ATTACK`).

## Où il apparaît dans les réponses de l'API

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

La réponse autonome encapsule le résultat sous un unique objet `age_estimation` de premier niveau, aux côtés de `request_id` et des données renvoyées `vendor_data` / `metadata`. Lorsque `save_api_request=true` (valeur par défaut), `request_id` correspond à l'identifiant de session conservé et le résultat peut également être récupéré ultérieurement depuis l'endpoint de décision ; lorsque sa valeur est `false`, il s'agit d'un UUID de corrélation ponctuel.

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

### Décision de workflow — `GET /v3/session/{session_id}/decision/`

Dans une session de workflow, l'âge prédit est **intégré au sein du rapport de détection du vivant — il n'y a pas de tableau d'estimation de l'âge séparé**. L'endpoint de décision V3 renvoie les rapports de détection du vivant sous la clé de tableau au pluriel **`liveness_checks`** (`ReducedSessionV3DecisionSerializer.get_liveness_checks`), et chaque entrée comporte une valeur décimale `age_estimation` — l'âge estimé du plus grand visage détecté — ou `null` si aucun âge n'a été calculé (`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,
      "...": "..."
    }
  ]
}
```

Lisez l'âge à partir de `liveness_checks[].age_estimation`. Les appels autonomes conservés (`save_api_request=true`) apparaissent de la même manière sur l'endpoint de décision, avec `features` contenant `AGE_ESTIMATION`.

## Schéma

Le schéma canonique champ par champ se trouve sur la page [Modèles de données](https://docs.didit.me/fr/reference/data-models.md#estimation-de-l’âge). La structure de réponse autonome est documentée par `AgeEstimationResponseSerializer` et assemblée dans `AgeEstimationAPIView` ; la valeur pour le workflow est produite par `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[];
}
```

### Valeurs de statut

Les chaînes de statut proviennent de l'énumération partagée des statuts de fonctionnalités (voir [Énumérations de statut](https://docs.didit.me/fr/reference/data-models.md#référence-des-énumérations-de-statut)). L'endpoint autonome ne renvoie que :

| Statut | Signification |
| - | - |
| `Approved` | Aucun avertissement ne s'est déclenché — le sujet est bien vivant et l'âge prédit respecte le seuil configuré. |
| `Declined` | Au moins un avertissement s'est déclenché — score de détection du vivant faible, âge inférieur au seuil, aucun visage, aucun âge ou attaque. |

Dans les sessions de workflow, la vérification de détection du vivant peut également aboutir à `In Review` lorsqu'un risque configurable se déclenche avec une action d'examen (par exemple `POSSIBLE_DUPLICATED_FACE`). Consultez la [référence des énumérations de statut](https://docs.didit.me/fr/reference/data-models.md#référence-des-énumérations-de-statut).

## Exemples

### Approuvé — autonome, sujet adulte

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

### Refusé — autonome, âge prédit inférieur au seuil

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

### Approuvé — intégré dans un rapport de détection du vivant de 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": []
}
```

## Note de sécurité

Toutes les URL d'images et de vidéos renvoyées dans la réponse sont des liens pré-signés avec une durée de validité limitée. Traitez-les comme des références à courte durée de vie — ne les partagez pas publiquement et appelez à nouveau l'endpoint de décision pour actualiser les URL expirées. Par bonne pratique, conservez uniquement le statut de vérification et les valeurs de confiance de votre côté plutôt que les médias biométriques sous-jacents.

## Liens connexes

* [Présentation de l'Estimation de l'âge](https://docs.didit.me/fr/core-technology/age-estimation/overview.md) — fonctionnement de la fonctionnalité, tarifs, logique de décision.
* [Avertissements de l'Estimation de l'âge](https://docs.didit.me/fr/core-technology/age-estimation/warnings-age-estimation.md) — tous les codes de risque et déclencheurs de refus.
* [Référence de l'API autonome](https://docs.didit.me/fr/standalone-apis/age-estimation.md) — requête et réponse de `POST /v3/age-estimation/`.
* [Modèles de données — estimation de l'âge](https://docs.didit.me/fr/reference/data-models.md#estimation-de-l’âge) — schéma canonique champ par champ.
* [Détection du vivant passive](https://docs.didit.me/fr/core-technology/liveness/overview.md) — le modèle partagé de détection du vivant utilisé dans les réponses d'estimation de l'âge.


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