Altersschätzungsbericht: JSON-Schema & Felder

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

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

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.

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

{
  "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. Die Struktur der Standalone-Antwort wird durch AgeEstimationResponseSerializer dokumentiert und in AgeEstimationAPIView zusammengestellt; der Workflow-Wert wird von LivenessV3Serializer erzeugt.

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

Beispiele

Approved — Standalone, erwachsene Person

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

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

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

Authentifizierung

Verifizierung

Überwachung

Plattform

Altersschätzungsbericht: JSON-Schema & Felder

Übersicht

Vorkommen in API-Antworten

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

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

Schema

Statuswerte

Beispiele

Approved — Standalone, erwachsene Person

Declined — Standalone, vorhergesagtes Alter unter dem Schwellenwert

Approved — eingebettet in einen Workflow-Liveness-Bericht

Sicherheitshinweis

Verwandte Themen

​Übersicht

​Vorkommen in API-Antworten

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

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

​Schema

​Statuswerte

​Beispiele

​Approved — Standalone, erwachsene Person

​Declined — Standalone, vorhergesagtes Alter unter dem Schwellenwert

​Approved — eingebettet in einen Workflow-Liveness-Bericht

​Sicherheitshinweis

​Verwandte Themen

Übersicht

Vorkommen in API-Antworten

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

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

Schema

Statuswerte

Beispiele

Approved — Standalone, erwachsene Person

Declined — Standalone, vorhergesagtes Alter unter dem Schwellenwert

Approved — eingebettet in einen Workflow-Liveness-Bericht

Sicherheitshinweis

Verwandte Themen