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.
`photo_redaction`	ei	redact (oletus) poistaa kasvokuvan. keep jättää sen näkyviin ja lisää warnings-koodin photo_not_redacted. both palauttaa kaksi kuvaa: täysin sensuroidun ja kuvallisen.

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 — 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 — 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. Kahdeksan mahdollista koodia:

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

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

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