Informe d'estimació d'edat: esquema JSON i camps

L’informe d’Estimació d’edat recull una edat predita pel model (en anys) per a la cara més gran detectada en una imatge, combinada amb una comprovació passiva de prova de vida que confirma que el subjecte és una persona real i no pas una foto, una pantalla o una màscara. Les dues comprovacions s’executen sempre juntes: l’Estimació d’edat mai no retorna una edat sense una puntuació de prova de vida. Aquesta pàgina documenta l’estructura JSON que retornen ambdues vies de crida: l’endpoint independent POST /v3/age-estimation/ i el camp incrustat age_estimation als informes de prova de vida del flux de treball.

Informe d'estimació d'edat de Didit amb l'edat predita, la puntuació de prova de vida passiva i les mètriques de qualitat facial

Visió general

L’Estimació d’edat té dos modes de lliurament:

API independent. POST /v3/age-estimation/ accepta una sola imatge facial (user_image) i retorna l’edat predita i la puntuació de prova de vida passiva de manera síncrona. Consulta la referència de l’API independent d’Estimació d’edat.
Incrustada en un flux de treball. Cada informe de prova de vida d’un flux de treball inclou l’edat predita sota age_estimation; el valor s’obté sempre a partir de la cara més gran detectada. Els llindars d’edat només s’apliquen (generant advertències d’edat) en fluxos d’estimació d’edat: fluxos de treball de verificació d’edat adaptatius o nodes de flux de treball AGE_ESTIMATION.

Cada informe conté:

L’estat general status (Approved, Declined).
El mètode de prova de vida method (sempre PASSIVE a l’API independent; ACTIVE_3D / FLASHING / PASSIVE als fluxos de treball).
Una puntuació score de prova de vida (0–100; com més alta, més confiança en el fet que el subjecte està viu; null es tracta com a 0 per a les comprovacions de llindar).
L’edat predita age_estimation en anys (float, per exemple 27.33; null quan no s’ha pogut estimar l’edat de cap cara).
Només en mode independent: un objecte user_image amb un array entities[] (una entrada per cara detectada: age, bbox, confidence, gender) i l’orientació best_angle.
Només en flux de treball: reference_image, video_url, matches[], i les mètriques de qualitat de prova de vida passiva face_quality (0–100%) i face_luminance (0–100%). La resposta independent no inclou aquests camps.
Un array warnings[] d’esdeveniments de risc emesos durant la comprovació (consulta Advertències d’Estimació d’edat).

La decisió en mode independent és Declined sempre que warnings no estigui buit; Approved requereix un array buit. Les advertències s’activen quan:

La puntuació de prova de vida score és igual o inferior a face_liveness_score_decline_threshold (per defecte 30) — LOW_LIVENESS_SCORE.
L’edat predita està per sota d’age_estimation_decline_threshold (per defecte 18) — AGE_BELOW_MINIMUM. Defineix el llindar a 0 per desactivar la comprovació d’edat.
No es detecta cap cara (NO_FACE_DETECTED) o no s’ha pogut estimar l’edat de cap cara (AGE_NOT_DETECTED).
El model de prova de vida detecta un atac de presentació (LIVENESS_FACE_ATTACK).

On apareix a les respostes de l’API

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

La resposta independent embolcalla el resultat sota un únic objecte age_estimation de nivell superior, juntament amb request_id i les dades vendor_data / metadata retornades. Quan save_api_request=true (per defecte), request_id és l’identificador de sessió persistit i el resultat també es pot obtenir més endavant des de l’endpoint de decisió; quan és false, és un UUID de correlació d’un sol ús.

{
  "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ó del flux de treball — `GET /v3/session/{session_id}/decision/`

En una sessió de flux de treball, l’edat predita està incrustada dins de l’informe de prova de vida; no hi ha cap array separat d’estimació d’edat. L’endpoint de decisió V3 retorna els informes de prova de vida sota la clau plural de l’array liveness_checks (ReducedSessionV3DecisionSerializer.get_liveness_checks), i cada entrada conté un valor age_estimation de tipus float (l’edat estimada de la cara més gran detectada) o null si no s’ha calculat cap edat (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,
      "...": "..."
    }
  ]
}

Llegeix l’edat de liveness_checks[].age_estimation. Les crides independents persistides (save_api_request=true) apareixen de la mateixa manera a l’endpoint de decisió, amb features contenint AGE_ESTIMATION.

Esquema

L’esquema canònic camp per camp es troba a la pàgina Models de dades. L’estructura de resposta independent està documentada per AgeEstimationResponseSerializer i es construeix a AgeEstimationAPIView; el valor del flux de treball el produeix 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[];
}

Valors d’estat

Les cadenes d’estat provenen de l’enumeració compartida d’estats de funcionalitats (consulta Enumeracions d’estat). L’endpoint independent només retorna:

Estat	Significat
`Approved`	No s’ha activat cap advertència: el subjecte està viu i l’edat predita compleix el llindar configurat.
`Declined`	S’ha activat almenys una advertència: puntuació de prova de vida baixa, edat per sota del llindar, absència de cara, absència d’edat o atac.

En sessions de flux de treball, la comprovació de prova de vida també pot resoldre’s en In Review quan s’activa un risc configurable amb una acció de revisió (per exemple POSSIBLE_DUPLICATED_FACE). Consulta la referència d’enumeracions d’estat.

Exemples

Approved — independent, subjecte adult

{
  "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 — independent, edat predita per sota del llindar

{
  "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 — incrustat en un informe de prova de vida de flux de treball

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

Tots els URL d’imatges i vídeos que es retornen a la resposta són enllaços pre-signats amb un període de validesa limitat. Tracta’ls com a referències de curta durada: no els comparteixis públicament i torna a cridar l’endpoint de decisió per actualitzar els URL caducats. Com a bona pràctica, emmagatzema al teu sistema només l’estat de la verificació i els valors de confiança en comptes dels arxius multimèdia biomètrics subjacents.

Relacionat

Visió general d’Estimació d’edat — comportament de la funcionalitat, preus i lògica de decisió.
Advertències d’Estimació d’edat — tots els codis de risc i activadors de rebuig.
Referència de l’API independent — sol·licitud i resposta de POST /v3/age-estimation/.
Models de dades: estimació d’edat — esquema canònic camp per camp.
Prova de vida passiva — el model compartit de prova de vida utilitzat a les respostes d’estimació d’edat.

Autenticació

Verificació

Monitoratge

Plataforma

Informe d'estimació d'edat: esquema JSON i camps

Visió general

On apareix a les respostes de l’API

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

Decisió del flux de treball — `GET /v3/session/{session_id}/decision/`

Esquema

Valors d’estat

Exemples

Approved — independent, subjecte adult

Declined — independent, edat predita per sota del llindar

Approved — incrustat en un informe de prova de vida de flux de treball

Nota de seguretat

Relacionat

​Visió general

​On apareix a les respostes de l’API

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

​Decisió del flux de treball — GET /v3/session/{session_id}/decision/

​Esquema

​Valors d’estat

​Exemples

​Approved — independent, subjecte adult

​Declined — independent, edat predita per sota del llindar

​Approved — incrustat en un informe de prova de vida de flux de treball

​Nota de seguretat

​Relacionat

Visió general

On apareix a les respostes de l’API

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

Decisió del flux de treball — `GET /v3/session/{session_id}/decision/`

Esquema

Valors d’estat

Exemples

Approved — independent, subjecte adult

Declined — independent, edat predita per sota del llindar

Approved — incrustat en un informe de prova de vida de flux de treball

Nota de seguretat

Relacionat