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

Référence API

L'API IDBird est volontairement petite : deux endpoints, une forme de requête, une enveloppe d'erreur. Cette page en est la surface complète. La spécification machine et la référence interactive vivent sur api.idbird.eu.

URL de base et authentification

Chaque requête porte une clé API Bearer délivrée par l'équipe IDBird. Les clés ne sont stockées qu'en hachage SHA-256 et vérifiées en direct à chaque requête — une révocation prend effet dès l'appel suivant.

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

Endpoints

`POST`	`/v1/redact`	Caviarder un document et recevoir l'image nettoyée plus findings et warnings.
`POST`	`/v1/inspect`	Essai à blanc : findings et warnings seulement — aucune image n'est jamais renvoyée.
`GET`	`/up`	Contrôle de santé, sans authentification.

Requête

Les deux endpoints acceptent la même requête multipart/form-data.

Champ	Requis	Description
`document`	oui	Le fichier : JPEG, PNG, BMP ou PDF (jusqu'à 5 pages par défaut), 10 Mio max. Le type est déduit du contenu — nom de fichier et en-tête Content-Type sont ignorés.
`country_hint`	non	Code ISO 3166-1 alpha-2 du pays émetteur, insensible à la casse (EL est accepté comme alias de GR). Sans indication, mode automatique — avec, la détection est plus fine.
`redact_photo`	non	true (défaut) supprime la photo. false la laisse visible et ajoute le warning photo_not_redacted. both renvoie deux images : entièrement caviardée, et photo visible.
`redact_documentnumber`	non	false (défaut) laisse lisible le numéro du document lui-même et ajoute le warning document_number_not_redacted lorsqu'un numéro est détecté. true le détruit. Les numéros nationaux et la MRZ sont toujours détruits.

curl https://api.idbird.eu/v1/redact \
  -H "Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -F document=@passport-scan.jpg \
  -F country_hint=NL

Réponses

Le champ image est toujours un PNG encodé en base64 et toujours la version la plus caviardée de la requête. findings contient des noms de détecteurs et des nombres — jamais de valeurs. warnings et findings sont toujours présents, vides quand tout est net.

POST /v1/redact — une seule page

{
  "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 — redact_photo=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 — PDF multipage (pages remplace image, numérotation dès 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 — findings seulement, jamais d'image

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

Codes d'avertissement

HTTP 200 signifie traité, pas protégé. Les warnings arrivent dans un ordre fixe et documenté ; vérifiez-les avant d'archiver. Les neuf codes possibles :

nothing_detected: Rien de reconnaissable n'a été trouvé ; l'image est renvoyée inchangée. Ne l'archivez pas comme caviardée sans vérification.
no_country_hint: La détection des numéros nationaux a tourné en mode automatique. Fournissez country_hint pour une détection plus précise.
country_detectors_unavailable: Aucune détection de numéro propre au pays indiqué ; caviardage au niveau MRZ uniquement. Le numéro national imprimé peut rester visible — vérifiez.
country_detector_no_match: Les détecteurs pays ont tourné, mais aucun numéro national n'a été détecté. Si le document en porte un visiblement, il peut subsister — vérifiez.
mrz_not_found: Aucune zone de lecture automatique détectée — absente de ce côté, coupée ou illisible. Attendu pour le recto des cartes d'identité.
missing_face_finding: Aucune photo d'identité détectée. Généralement sans gravité pour les pages ne contenant que du texte.
missing_signature_finding: Aucune signature détectée. Généralement sans gravité pour les pages qui n'en portent pas.
photo_not_redacted: redact_photo=false a été demandé : la copie renvoyée garde la photo visible. Traitez-la en conséquence.
document_number_not_redacted: Un numéro de document a été détecté et laissé visible — le comportement par défaut. Envoyez redact_documentnumber=true s'il doit être détruit.

Erreurs

Toutes les erreurs utilisent une enveloppe unique, avec un code stable et un message statique en anglais — sûr pour le matching, sans aucun contenu de document :

{
  "error": {
    "code": "country_not_supported",
    "message": "The issuing country \"US\" is not supported by this service."
  }
}

HTTP	code	message
`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`	`redact_photo_invalid`	The redact_photo field must be one of: true, false, both.
`422`	`redact_documentnumber_invalid`	The redact_documentnumber field must be one of: true, false.
`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.

Limites et facturation

Limite de débit : 30 requêtes par minute et par clé ; 429 avec en-tête Retry-After en cas de dépassement.
Quota quotidien : 50 appels par clé et par jour par défaut (UTC) ; relevé par clé par l'équipe IDBird, à effet immédiat.
Une requête entièrement traitée est un appel facturable — PDF multipage compris. Les requêtes rejetées (4xx) ou échouées (5xx) ne sont jamais facturées, et le quota est vérifié avant traitement : une requête au-dessus du quota ne coûte rien.

Couverture pays

Numéro national + MRZ + photo + signature

NL Pays-Bas
DE Allemagne
FR France
ES Espagne
AT Autriche
BE Belgique
HR Croatie
CZ Tchéquie
DK Danemark
FI Finlande
IE Irlande
IT Italie
PL Pologne
PT Portugal
SE Suède

Pour la Belgique et l'Allemagne, les détecteurs propres au pays ciblent le numéro du document, conservé par défaut — envoyez redact_documentnumber=true pour le détruire. MRZ, photo et signature sont toujours couvertes.

MRZ + photo + signature

BG Bulgarie
CY Chypre
EE Estonie
GR Grèce
HU Hongrie
LV Lettonie
LT Lituanie
LU Luxembourg
MT Malte
RO Roumanie
SK Slovaquie
SI Slovénie

Les documents de tout autre pays émetteur sont refusés d'emblée — jamais à moitié caviardés en silence.

Documentation machine

La spécification OpenAPI 3.1 est épinglée à l'implémentation par un test CI : chaque code d'erreur et chaque warning que le service peut émettre doit être documenté, et rien de plus. La documentation ne peut pas dériver.

Référence interactive (Redoc) openapi.yaml llms-full.txt