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

API-viite

IDBird Redaction API on tarkoituksella pieni: kaksi endpointtia, yksi pyyntömuoto, yksi virhekuori. Tämä sivu on koko rajapinta. Koneellisesti luettava spesifikaatio ja interaktiivinen viite ovat osoitteessa api.idbird.eu.

Perus-URL ja todennus

Jokainen pyyntö kantaa IDBird-tiimin myöntämää Bearer-API-avainta. Avaimet tallennetaan vain SHA-256-hasheina ja tarkistetaan reaaliajassa jokaisella pyynnöllä — kumoaminen vaikuttaa heti seuraavaan kutsuun.

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

Endpointit

`POST`	`/v1/redact`	Sensuroi asiakirja ja vastaanota puhdistettu kuva sekä findings ja warnings.
`POST`	`/v1/inspect`	Kuiva-ajo: vain findings ja warnings — kuvaa ei koskaan palauteta.
`GET`	`/up`	Toimivuustarkistus, ilman todennusta.

Pyyntö

Molemmat endpointit hyväksyvät saman multipart/form-data-pyynnön.

Kenttä	Pakollinen	Kuvaus
`document`	kyllä	Tiedosto: JPEG, PNG, BMP tai PDF (oletuksena enintään 5 sivua), enintään 10 MiB. Tyyppi tunnistetaan tiedoston sisällöstä — tiedostonimi ja Content-Type-otsake ohitetaan.
`country_hint`	ei	Myöntäjämaan ISO 3166-1 alpha-2 -koodi, kirjainkoosta riippumaton (EL hyväksytään GR:n aliaksena). Ilman sitä ajetaan automaattitila — vihjeen kanssa tunnistus on tarkempi.
`redact_photo`	ei	true (oletus) poistaa kasvokuvan. false jättää sen näkyviin ja lisää warnings-koodin photo_not_redacted. both palauttaa kaksi kuvaa: täysin sensuroidun ja kuvallisen.
`redact_documentnumber`	ei	false (oletus) jättää asiakirjan oman numeron luettavaksi ja lisää warnings-koodin document_number_not_redacted, kun numero havaitaan. true tuhoaa sen. Kansalliset numerot ja MRZ tuhotaan aina.

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

Vastaukset

Kenttä image on aina base64-koodattu PNG ja aina pyynnön sensuroiduin versio. findings sisältää tunnistimien nimet ja lukumäärät — ei koskaan arvoja. warnings ja findings ovat aina läsnä, tyhjinä kun kaikki on puhdasta.

POST /v1/redact — yksi sivu

{
  "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 — monisivuinen PDF (pages korvaa imagen, numerointi alkaa 1:stä)

{
  "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 — vain findings, ei koskaan kuvaa

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

Varoituskoodit

HTTP 200 tarkoittaa käsiteltyä, ei suojattua. Warnings-koodit tulevat kiinteässä, dokumentoidussa järjestyksessä; tarkista ne ennen arkistointia. Yhdeksän mahdollista koodia:

nothing_detected: Mitään tunnistettavaa ei löytynyt; kuva palautetaan muuttumattomana. Älä arkistoi sitä sensuroituna ilman tarkistusta.
no_country_hint: Kansallisten numeroiden tunnistus ajettiin automaattitilassa. Anna country_hint tarkempaa tunnistusta varten.
country_detectors_unavailable: Annetulle maalle ei ole maakohtaista numerontunnistusta; sensurointi vain MRZ-tasolla. Painettu kansallinen numero voi jäädä näkyviin — tarkista.
country_detector_no_match: Maakohtaiset tunnistimet ajettiin, mutta kansallista numeroa ei havaittu. Jos asiakirjassa sellainen näkyy, se voi olla jäljellä — tarkista.
mrz_not_found: Koneellisesti luettavaa aluetta ei havaittu — puuttuu tältä puolelta, rajautunut pois tai lukukelvoton. Odotettavissa henkilökorttien etupuolilla.
missing_face_finding: Kasvokuvaa ei havaittu. Yleensä kunnossa pelkkää tekstiä sisältävillä sivuilla.
missing_signature_finding: Allekirjoitusta ei havaittu. Yleensä kunnossa sivuilla, joilla sitä ei ole.
photo_not_redacted: Pyynnössä oli redact_photo=false: palautettu kopio pitää kasvokuvan näkyvissä. Käsittele se sen mukaisesti.
document_number_not_redacted: Asiakirjan numero havaittiin ja jätettiin näkyviin — oletus. Lähetä redact_documentnumber=true, jos se pitää tuhota.

Virheet

Kaikki virheet käyttävät yhtä kuorta, jossa on vakaa koodi ja staattinen englanninkielinen viesti — turvallinen vertailtavaksi, vapaa asiakirjan sisällöstä:

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

Rajat ja laskutus

Nopeusraja: 30 pyyntöä minuutissa per avain; ylityksestä 429 ja Retry-After-otsake.
Päiväkiintiö: oletuksena 50 kutsua per avain per päivä (UTC); IDBird-tiimi korottaa sitä avainkohtaisesti, voimaan heti.
Yksi kokonaan käsitelty pyyntö on yksi laskutettava kutsu — monisivuinen PDF mukaan lukien. Hylätyistä (4xx) ja epäonnistuneista (5xx) pyynnöistä ei koskaan laskuteta, ja kiintiö tarkistetaan ennen käsittelyä: kiintiön ylittävä pyyntö ei maksa mitään.

Maakattavuus

Kansallinen numero + MRZ + kuva + allekirjoitus

NL Alankomaat
DE Saksa
FR Ranska
ES Espanja
AT Itävalta
BE Belgia
HR Kroatia
CZ Tšekki
DK Tanska
FI Suomi
IE Irlanti
IT Italia
PL Puola
PT Portugali
SE Ruotsi

Belgian ja Saksan maakohtaiset tunnistimet kohdistuvat asiakirjan numeroon, joka säilytetään oletuksena — lähetä redact_documentnumber=true tuhotaksesi sen. MRZ, kasvokuva ja allekirjoitus katetaan aina.

MRZ + kuva + allekirjoitus

BG Bulgaria
CY Kypros
EE Viro
GR Kreikka
HU Unkari
LV Latvia
LT Liettua
LU Luxemburg
MT Malta
RO Romania
SK Slovakia
SI Slovenia

Kaikkien muiden myöntäjämaiden asiakirjat hylätään suoraan — ei koskaan hiljaa puoliksi sensuroitu.

Koneellisesti luettava dokumentaatio

OpenAPI 3.1 -spesifikaatio on kiinnitetty toteutukseen CI-testillä: jokainen virhekoodi ja warnings-koodi, jonka palvelu voi antaa, on dokumentoitava — eikä mitään muuta. Dokumentaatio ei voi ajautua harhaan.

Interaktiivinen viite (Redoc) openapi.yaml llms-full.txt