Altersprüfung-API

Schätzen Sie anhand eines Selfies, ob eine Person alt genug ist, mit einem Rückgriff auf das Geburtsdatum aus dem Ausweis, wenn die Schätzung zu nah an der Grenze liegt.

POST /api/v1/kyc/age-estimation schätzt, wie alt das Gesicht auf einem Selfie wirkt, und vergleicht es mit einem Mindestalter. Es ist dieselbe Prüfung wie die Option Altersprüfung in Formularen (siehe Altersprüfung), aber eigenständig verfügbar.

Das Ergebnis ist eine Schätzung aus einem Foto, kein Altersnachweis. Jede Antwort weist darauf hin (isEstimate, disclaimer). Nahe an Ihrer Grenze lautet die Antwort absichtlich inconclusive: greifen Sie dann auf eine Ausweisprüfung zurück.

Authentifizieren Sie sich mit einem API-Schlüssel (Authorization: Bearer ck_live_…) mit dem Berechtigungsbereich kyc:write. Siehe Authentifizierung. Das Foto wird im Arbeitsspeicher verarbeitet und nie gespeichert.

Anfrage

Senden Sie entweder multipart/form-data oder JSON.

curl -X POST https://app.certivant.com/api/v1/kyc/age-estimation \
  -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  -H "Idempotency-Key: signup-8841" \
  -F image=@selfie.jpg \
  -F minAge=18 \
  -F buffer=5

{
  "imageBase64": "/9j/4AAQSkZJRg…",
  "minAge": 18,
  "buffer": 5,
  "dateOfBirth": "1990-02-03"
}

Feld	Typ	Hinweise
`image` / `imageBase64`	Datei / string	Ein frontal aufgenommenes Selfie mit einem einzelnen Gesicht. JPEG, PNG, WebP oder HEIC, bis zu 10 MB. Eine `data:`-URL wird akzeptiert
`minAge`	Ganzzahl 1–120, optional	Standard ist die Einstellung Ihrer Organisation (Einstellungen → Betrugsprävention), zunächst 18
`buffer`	Ganzzahl 0–30, optional	Jahre vor und nach `minAge`, innerhalb derer die Schätzung nicht als verlässlich gilt. Standard ist die Einstellung Ihrer Organisation, zunächst 5
`dateOfBirth`	`YYYY-MM-DD`, optional	Das Geburtsdatum aus einem Ausweis, den Sie bereits verifiziert haben. Wird verwendet, wenn die Schätzung nicht eindeutig ist

Senden Sie einen Header Idempotency-Key, damit ein erneuter Versuch kostenlos ist: Derselbe Schlüssel wird nur einmal berechnet.

Antwort

{
  "data": {
    "result": "pass",
    "method": "estimate",
    "minAge": 18,
    "buffer": 5,
    "isEstimate": true,
    "estimatedAge": 31.4,
    "estimateSpread": 3.2,
    "estimateConfidence": "high",
    "disclaimer": "An estimate from a photo, not proof of age.",
    "chargedCents": 7
  }
}

Feld	Hinweise
`result`	`pass`, `fail` oder `inconclusive`
`method`	`estimate` — das Selfie hat entschieden; `id_document` — `dateOfBirth` hat entschieden; `none` — nichts konnte entscheiden
`isEstimate`	`true`, wenn die Schätzung aus dem Selfie Teil der Antwort ist
`estimatedAge`, `estimateSpread`, `estimateConfidence`	Die Schätzung in Jahren, wie unsicher sie ist, und `high` oder `low`. Vorhanden, wenn eine Schätzung erstellt wurde
`idAge`	Alter in vollen Jahren aus `dateOfBirth`, sofern es verwendet wurde
`fallbackReason`	Warum der Ausweis nötig war: `near_limit`, `low_confidence`, `no_estimate` oder `estimate_mismatch`
`mismatch`	Eine verlässliche Schätzung und der Ausweis widersprechen sich. Behandeln Sie dies als Fall für die manuelle Prüfung
`idCheckRequired`	`true`, wenn das Ergebnis `inconclusive` ist und Sie kein `dateOfBirth` gesendet haben: Führen Sie eine Ausweisprüfung durch und rufen Sie erneut mit dem Geburtsdatum auf, oder schicken Sie die Person in eine Verifizierung
`disclaimer`	Ist immer vorhanden. Zeigen Sie ihn überall dort an, wo Sie die Schätzung darstellen
`chargedCents`	Was dieser Aufruf gekostet hat

So wird die Entscheidung getroffen

Schätzung mindestens minAge + buffer → pass.
Schätzung unterhalb von minAge − buffer → fail.
Dazwischen oder ist das Modell sich bei seiner Schätzung unsicher → entscheidet das dateOfBirth, sofern Sie eines gesendet haben. Ohne dieses lautet das Ergebnis inconclusive.
Wenn Sie ein dateOfBirth senden, das der Schätzung klar widerspricht, ist mismatch true: Eine Schätzung weit über der Grenze mit einem minderjährigen Geburtsdatum ist ein fail (das Geburtsdatum gewinnt); eine Schätzung weit unter der Grenze mit einem volljährigen Geburtsdatum ist inconclusive, damit ein Mensch sie prüft.

Fehler

Status	Wann
`400`	Bild, `minAge`, `buffer` oder `dateOfBirth` fehlen oder sind ungültig
`402`	Nicht genug Guthaben, um die Prüfung durchzuführen
`403`	Die Altersschätzung ist nicht in Ihrem Tarif enthalten
`413`	Bild größer als 10 MB
`415`	Kein unterstützter Bildtyp
`422`	Kein verwertbares Gesicht gefunden (und kein `dateOfBirth`, auf das zurückgegriffen werden könnte)
`502`	Der Schätzdienst ist nicht verfügbar. Wiederholen Sie den Aufruf mit demselben `Idempotency-Key`

Wird kein Gesicht gefunden, Sie haben aber ein dateOfBirth gesendet, antwortet der Aufruf dennoch aus dem Ausweis (method: "id_document").

Abrechnung

Die Altersschätzung ist eine Funktion des Tarifs mit einem im Monat enthaltenen Kontingent und einem Preis pro Prüfung nach Verbrauch (Pay-as-you-go) aus Ihrem Guthaben. Ein Aufruf, der 402 oder 403 liefert, wird nicht berechnet. Jede Prüfung wird in Ihrem Audit-Protokoll (age_estimation.checked) mit Ergebnis und Methode festgehalten — nie aber mit dem Foto oder dem Geburtsdatum.

Bei einer Verifizierung

Ist die Altersprüfung in einem Formular aktiviert, enthält die Verifizierung selbst das Ergebnis: Ihre Prüfauslöser oder Ausschlussgründe können age_requirement_not_met oder age_check_inconclusive enthalten, und Richtlinien sowie Workflows können age.checked, age.result, age.method, age.estimatedAge, age.minimum, age.meetsMinimum und age.mismatch prüfen.