IDBird
DE
Kostenlos starten

API<REFERENCE<V1<<<<<<<<<<<<

API-Referenz

Die IDBird Redaction API ist bewusst klein: zwei Endpunkte, eine Request-Form, ein Fehler-Envelope. Diese Seite ist die vollständige Oberfläche. Die maschinenlesbare Spezifikation und die interaktive Referenz liegen auf api.idbird.eu.

Basis-URL & Authentifizierung

Jede Anfrage trägt einen Bearer-API-Key, ausgestellt vom IDBird-Team. Keys werden nur als SHA-256-Hash gespeichert und bei jeder Anfrage live geprüft — ein Widerruf greift ab der nächsten Anfrage.

https://api.idbird.eu
Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Endpunkte

POST /v1/redact Dokument schwärzen; zurück kommt das bereinigte Bild plus findings und warnings.
POST /v1/inspect Probelauf: nur findings und warnings — ein Bild wird niemals zurückgegeben.
GET /up Healthcheck, ohne Authentifizierung.

Request

Beide Endpunkte akzeptieren dieselbe multipart/form-data-Anfrage.

FeldPflichtBeschreibung
document ja Die Datei: JPEG, PNG, BMP oder PDF (standardmäßig bis 5 Seiten), max. 10 MiB. Der Typ wird aus dem Dateiinhalt erkannt — Dateiname und Content-Type-Header werden ignoriert.
country_hint nein ISO-3166-1-alpha-2-Code des Ausstellungslandes, Groß-/Kleinschreibung egal (EL gilt als Alias für GR). Ohne Angabe läuft der Automatikmodus — mit Hinweis ist die Erkennung schärfer.
photo_redaction nein redact (Standard) entfernt das Passfoto. keep lässt es sichtbar und ergänzt die Warning photo_not_redacted. both liefert zwei Bilder: vollständig geschwärzt und mit sichtbarem Foto. 
curl https://api.idbird.eu/v1/redact \
  -H "Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -F document=@passport-scan.jpg \
  -F country_hint=NL

Responses

Das Feld image ist immer ein Base64-kodiertes PNG und immer das am stärksten geschwärzte Ergebnis der Anfrage. findings enthält Detektornamen und Anzahlen — niemals Werte. warnings und findings sind immer vorhanden, leer wenn es nichts zu melden gibt.

POST /v1/redact — eine Seite

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_1": 1,
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_PASSPORT": 1,
    "OBJECT_TYPE/PERSON/FACE": 2,
    "OBJECT_TYPE/PERSON/SIGNATURE": 1
  }
}

POST /v1/redact — photo_redaction=both

{
  "image": "…fully redacted PNG…",
  "image_photo_visible": "…portrait intact, everything else redacted…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1
  }
}

POST /v1/redact — mehrseitiges PDF (pages ersetzt image, Zählung ab 1)

{
  "pages": [
    { "page": 1, "image": "iVBORw0KGgo…", "findings": { "OBJECT_TYPE/PERSON/FACE": 1 } },
    { "page": 2, "image": "iVBORw0KGgo…", "findings": { "MRZ_TD3_LINE_2": 1, "NETHERLANDS_BSN_NUMBER": 1 } }
  ],
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1,
    "OBJECT_TYPE/PERSON/FACE": 1
  }
}

POST /v1/inspect — nur Findings, niemals ein Bild

{
  "findings": {
    "NETHERLANDS_BSN_NUMBER": 1,
    "MRZ_TD3_LINE_2": 1
  },
  "warnings": ["no_country_hint"]
}

Warning-Codes

HTTP 200 heißt verarbeitet, nicht geschützt. Warnings erscheinen in fester, dokumentierter Reihenfolge; prüfen Sie sie vor dem Archivieren. Die acht möglichen Codes:

Fehler

Alle Fehler nutzen einen Envelope mit stabilem Code und statischer englischer Meldung — sicher zum Matchen, frei von Dokumentinhalten:

{
  "error": {
    "code": "country_not_supported",
    "message": "The issuing country \"US\" is not supported by this service."
  }
}
HTTPcodemessage
401 invalid_api_key The bearer API key is missing, unknown, or revoked.
404 not_found Not found.
405 method_not_allowed Method not allowed.
413 payload_too_large The document exceeds the 10 MiB limit.
415 unsupported_media_type The document must be a JPEG, PNG, BMP or PDF; the type is detected from file content.
422 country_hint_invalid The country_hint must be a two-letter ISO 3166-1 alpha-2 code.
422 country_not_supported The issuing country "US" is not supported by this service.
422 file_required The document file is required.
422 photo_redaction_invalid The photo_redaction field must be one of: redact, keep, both.
422 too_many_pages The PDF exceeds the 5-page limit; split it and submit the pages separately.
422 pdf_encrypted Encrypted PDFs are not supported.
422 unreadable_image The document could not be decoded as an image.
422 image_normalization_failed The image could not be reduced to the redaction backend request budget without degrading below the quality floor.
429 rate_limited Too many requests; retry later.
429 daily_quota_exceeded The daily allowance of 50 API call(s) for this key is exhausted for today (UTC).
500 internal_error Internal error.
502 dlp_unavailable The redaction backend is unavailable; no image was produced.

Limits & Abrechnung

  • Rate-Limit: 30 Anfragen pro Minute pro Key; bei Überschreitung 429 mit Retry-After-Header.
  • Tageskontingent: standardmäßig 50 Aufrufe pro Key pro Tag (UTC); vom IDBird-Team pro Key erhöht, mit sofortiger Wirkung.
  • Eine vollständig verarbeitete Anfrage ist ein abrechenbarer Aufruf — mehrseitiges PDF eingeschlossen. Abgelehnte (4xx) und fehlgeschlagene (5xx) Anfragen werden nie berechnet; das Kontingent wird vor der Verarbeitung geprüft, eine Anfrage über dem Limit kostet nichts.

Länderabdeckung

Kennnummer + MRZ + Foto + Unterschrift

  • NL Niederlande
  • DE Deutschland
  • FR Frankreich
  • ES Spanien
  • AT Österreich
  • BE Belgien
  • HR Kroatien
  • CZ Tschechien
  • DK Dänemark
  • FI Finnland
  • IE Irland
  • IT Italien
  • PL Polen
  • PT Portugal
  • SE Schweden

MRZ + Foto + Unterschrift

  • BG Bulgarien
  • CY Zypern
  • EE Estland
  • GR Griechenland
  • HU Ungarn
  • LV Lettland
  • LT Litauen
  • LU Luxemburg
  • MT Malta
  • RO Rumänien
  • SK Slowakei
  • SI Slowenien

Dokumente aus jedem anderen Ausstellungsland werden abgelehnt — niemals stillschweigend halb geschwärzt.

Maschinenlesbare Dokumentation

Die OpenAPI-3.1-Spezifikation ist per CI-Test an die Implementierung geheftet: Jeder Reason-Code und jede Warning, die der Dienst ausgeben kann, muss dokumentiert sein — und nichts darüber hinaus. Die Doku kann nicht abdriften.

Interaktive Referenz (Redoc) openapi.yaml llms-full.txt