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

# Altersschätzungsbericht: JSON-Schema & Felder

> Didit-Berichte zur Altersschätzung parsen: geschätztes Alter, Liveness-Scores, Schwellenwerte und Warncodes. Pay-per-Call ab $0.10.

Der Bericht zur Altersschätzung erfasst ein vom Modell vorhergesagtes Alter (in Jahren) für das größte in einem Bild erkannte Gesicht, kombiniert mit einer passiven Liveness-Erkennung, die bestätigt, dass es sich bei der Person um einen echten Menschen und nicht um ein Foto, einen Bildschirm oder eine Maske handelt. Beide Prüfungen laufen stets zusammen ab — die Altersschätzung gibt niemals ein Alter ohne einen Liveness-Score zurück.

Diese Seite dokumentiert die JSON-Struktur, die von beiden Aufrufpfaden zurückgegeben wird: dem Standalone-Endpoint `POST /v3/age-estimation/` und dem eingebetteten Feld `age_estimation` in Liveness-Berichten von Workflows.

![Didit-Bericht zur Altersschätzung mit vorhergesagtem Alter, passivem Liveness-Score und Messwerten zur Gesichtsqualität](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)

## Übersicht

Die Altersschätzung bietet zwei Bereitstellungsmodi:

* **Standalone-API.** `POST /v3/age-estimation/` nimmt ein einzelnes Gesichtsbild (`user_image`) entgegen und gibt das vorhergesagte Alter sowie den passiven Liveness-Score synchron zurück. Siehe die [API-Referenz zur Standalone-Altersschätzung](https://docs.didit.me/de/standalone-apis/age-estimation.md).
* **Eingebettet in einen Workflow.** Jeder Liveness-Bericht eines Workflows enthält das vorhergesagte Alter unter `age_estimation` — der Wert wird immer anhand des größten erkannten Gesichts ermittelt. Schwellenwerte für das Alter werden nur bei Abläufen zur Altersschätzung *erzwungen* (was Alterswarnungen auslöst): in Workflows zur adaptiven Altersverifizierung oder an `AGE_ESTIMATION`-Workflow-Knoten.

Jeder Bericht enthält:

* Den Gesamtstatus `status` (`Approved`, `Declined`).
* Die Liveness-Methode `method` (immer `PASSIVE` in der Standalone-API; `ACTIVE_3D` / `FLASHING` / `PASSIVE` in Workflows).
* Einen Liveness-Score `score` (0–100; höhere Werte bedeuten größeres Vertrauen darin, dass die Person echt ist; `null` wird bei Schwellenwertprüfungen wie `0` behandelt).
* Den vorhergesagten Wert `age_estimation` in Jahren (Float — zum Beispiel `27.33`; `null`, wenn kein Gesichtsalter geschätzt werden konnte).
* Nur Standalone: ein `user_image`-Objekt mit einem `entities[]`-Array (ein Eintrag pro erkanntem Gesicht — `age`, `bbox`, `confidence`, `gender`) und der Ausrichtung `best_angle`.
* Nur Workflow: `reference_image`, `video_url`, `matches[]` sowie die Qualitätsmetriken für passive Liveness `face_quality` (0–100%) und `face_luminance` (0–100%). Die Standalone-Antwort enthält diese Felder **nicht**.
* Ein `warnings[]`-Array — Risikoereignisse, die während der Prüfung ausgegeben werden (siehe [Warnungen der Altersschätzung](https://docs.didit.me/de/core-technology/age-estimation/warnings-age-estimation.md)).

Die Standalone-Entscheidung lautet immer dann `Declined`, wenn `warnings` nicht leer ist — `Approved` erfordert ein leeres Array. Warnungen werden ausgelöst, wenn:

* Der Liveness-Wert `score` bei oder unter `face_liveness_score_decline_threshold` liegt (Standardwert `30`) — `LOW_LIVENESS_SCORE`.
* Das vorhergesagte Alter unter `age_estimation_decline_threshold` liegt (Standardwert `18`) — `AGE_BELOW_MINIMUM`. Setzen Sie den Schwellenwert auf `0`, um die Altersprüfung zu deaktivieren.
* Kein Gesicht erkannt wird (`NO_FACE_DETECTED`) oder kein Gesichtsalter geschätzt werden konnte (`AGE_NOT_DETECTED`).
* Das Liveness-Modell einen Präsentationsangriff erkennt (`LIVENESS_FACE_ATTACK`).

## Vorkommen in API-Antworten

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

Die Standalone-Antwort kapselt das Ergebnis unter einem einzelnen `age_estimation`-Objekt auf oberster Ebene, zusammen mit `request_id` und den unverändert zurückgegebenen Feldern `vendor_data` / `metadata`. Wenn `save_api_request=true` gilt (Standardeinstellung), ist `request_id` die persistierte Sitzungs-ID, und das Ergebnis kann später auch über den Entscheidungs-Endpoint abgerufen werden; bei `false` handelt es sich um eine einmalige Korrelations-UUID.

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

### Workflow-Entscheidung — `GET /v3/session/{session_id}/decision/`

In einer Workflow-Sitzung ist das vorhergesagte Alter **im Liveness-Bericht eingebettet — es gibt kein separates Array für die Altersschätzung**. Der V3-Entscheidungs-Endpoint gibt Liveness-Berichte unter dem Plural-Array-Schlüssel **`liveness_checks`** zurück (`ReducedSessionV3DecisionSerializer.get_liveness_checks`), und jeder Eintrag enthält einen `age_estimation`-Float-Wert — das geschätzte Alter des größten erkannten Gesichts — oder `null`, falls kein Alter berechnet wurde (`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,
      "...": "..."
    }
  ]
}
```

Lesen Sie das Alter aus `liveness_checks[].age_estimation` aus. Persistierte Standalone-Aufrufe (`save_api_request=true`) erscheinen auf dieselbe Weise am Entscheidungs-Endpoint, wobei `features` den Wert `AGE_ESTIMATION` enthält.

## Schema

Das verbindliche Feld-für-Feld-Schema befindet sich auf der Seite [Datenmodelle](https://docs.didit.me/de/reference/data-models.md#altersschätzung). Die Struktur der Standalone-Antwort wird durch `AgeEstimationResponseSerializer` dokumentiert und in `AgeEstimationAPIView` zusammengestellt; der Workflow-Wert wird von `LivenessV3Serializer` erzeugt.

```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[];
}
```

### Statuswerte

Die Status-Strings stammen aus dem gemeinsamen Feature-Status-Enum (siehe [Status-Enums](https://docs.didit.me/de/reference/data-models.md#status-aufzählung)). Der Standalone-Endpoint gibt ausschließlich folgende Werte zurück:

| Status | Bedeutung |
| - | - |
| `Approved` | Es wurden keine Warnungen ausgelöst — die Person ist echt und das vorhergesagte Alter erfüllt den konfigurierten Schwellenwert. |
| `Declined` | Mindestens eine Warnung wurde ausgelöst — niedriger Liveness-Score, Alter unter Schwellenwert, kein Gesicht, kein Alter oder Angriff. |

In Workflow-Sitzungen kann die Liveness-Prüfung auch den Status `In Review` annehmen, wenn ein konfigurierbares Risiko mit einer Prüfaktion ausgelöst wird (beispielsweise `POSSIBLE_DUPLICATED_FACE`). Siehe die [Referenz zu Status-Enums](https://docs.didit.me/de/reference/data-models.md#status-aufzählung).

## Beispiele

### Approved — Standalone, erwachsene Person

```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 — Standalone, vorhergesagtes Alter unter dem Schwellenwert

```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 — eingebettet in einen Workflow-Liveness-Bericht

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

## Sicherheitshinweis

Alle in der Antwort zurückgegebenen Bild- und Video-URLs sind vorsignierte Links mit einem zeitlich begrenzten Gültigkeitsfenster. Behandeln Sie diese als kurzlebige Referenzen — geben Sie sie nicht öffentlich weiter und rufen Sie den Entscheidungs-Endpoint erneut auf, um abgelaufene URLs zu aktualisieren. Als bewährte Praxis sollten Sie auf Ihrer Seite nur den Verifizierungsstatus und die Konfidenzwerte speichern, anstatt die zugrunde liegenden biometrischen Mediendateien aufzubewahren.

## Verwandte Themen

* [Übersicht zur Altersschätzung](https://docs.didit.me/de/core-technology/age-estimation/overview.md) — Funktionsweise, Preise, Entscheidungslogik.
* [Warnungen der Altersschätzung](https://docs.didit.me/de/core-technology/age-estimation/warnings-age-estimation.md) — alle Risikocodes und Ablehnungsauslöser.
* [Standalone-API-Referenz](https://docs.didit.me/de/standalone-apis/age-estimation.md) — Anfrage und Antwort für `POST /v3/age-estimation/`.
* [Datenmodelle — Altersschätzung](https://docs.didit.me/de/reference/data-models.md#altersschätzung) — verbindliches Feld-für-Feld-Schema.
* [Passive Liveness-Erkennung](https://docs.didit.me/de/core-technology/liveness/overview.md) — das gemeinsame Liveness-Modell, das in Antworten zur Altersschätzung verwendet wird.


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