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

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

> Interpreta les respostes d'Estimació d'edat de Didit: edat estimada, prova de vida, llindars i advertències. Pagament per crida des de $0.10.

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](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)

## 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](https://docs.didit.me/ca/standalone-apis/age-estimation.md).
* **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](https://docs.didit.me/ca/core-technology/age-estimation/warnings-age-estimation.md)).

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.

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

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

```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,
      "...": "..."
    }
  ]
}
```

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](https://docs.didit.me/ca/reference/data-models.md#estimació-d’edat). L'estructura de resposta independent està documentada per `AgeEstimationResponseSerializer` i es construeix a `AgeEstimationAPIView`; el valor del flux de treball el produeix `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[];
}
```

### Valors d'estat

Les cadenes d'estat provenen de l'enumeració compartida d'estats de funcionalitats (consulta [Enumeracions d'estat](https://docs.didit.me/ca/reference/data-models.md#referència-d’enumeració-d’estats)). 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](https://docs.didit.me/ca/reference/data-models.md#referència-d’enumeració-d’estats).

## Exemples

### Approved — independent, subjecte adult

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

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

```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 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](https://docs.didit.me/ca/core-technology/age-estimation/overview.md) — comportament de la funcionalitat, preus i lògica de decisió.
* [Advertències d'Estimació d'edat](https://docs.didit.me/ca/core-technology/age-estimation/warnings-age-estimation.md) — tots els codis de risc i activadors de rebuig.
* [Referència de l'API independent](https://docs.didit.me/ca/standalone-apis/age-estimation.md) — sol·licitud i resposta de `POST /v3/age-estimation/`.
* [Models de dades: estimació d'edat](https://docs.didit.me/ca/reference/data-models.md#estimació-d’edat) — esquema canònic camp per camp.
* [Prova de vida passiva](https://docs.didit.me/ca/core-technology/liveness/overview.md) — el model compartit de prova de vida utilitzat a les respostes d'estimació d'edat.


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