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

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

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

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.

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

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

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

Exemples

Approuvé — autonome, sujet adulte

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

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

{
  "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 — fonctionnement de la fonctionnalité, tarifs, logique de décision.
Avertissements de l’Estimation de l’âge — tous les codes de risque et déclencheurs de refus.
Référence de l’API autonome — requête et réponse de POST /v3/age-estimation/.
Modèles de données — estimation de l’âge — schéma canonique champ par champ.
Détection du vivant passive — le modèle partagé de détection du vivant utilisé dans les réponses d’estimation de l’âge.

Authentification

Vérification

Surveillance

Plateforme

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

Présentation

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

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

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

Schéma

Valeurs de statut

Exemples

Approuvé — autonome, sujet adulte

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

Approuvé — intégré dans un rapport de détection du vivant de workflow

Note de sécurité

Liens connexes

​Présentation

​Où il apparaît dans les réponses de l’API

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

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

​Schéma

​Valeurs de statut

​Exemples

​Approuvé — autonome, sujet adulte

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

​Approuvé — intégré dans un rapport de détection du vivant de workflow

​Note de sécurité

​Liens connexes

Présentation

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

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

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

Schéma

Valeurs de statut

Exemples

Approuvé — autonome, sujet adulte

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

Approuvé — intégré dans un rapport de détection du vivant de workflow

Note de sécurité

Liens connexes