Endpunkt-Referenz

POST /scan/crop

Sie senden ein Dokumentenfoto und bekommen einen sauberen, geraden, knapp zugeschnittenen Scan zurück. Dieser Endpunkt steht hinter dem Schnellstart und wird in fast jeder Integration zuerst benutzt.

Anfragevertrag

Feld	Erforderlich	Funktion
file	ja (eine Seite)	Ein Bild als Multipart-Formulardaten. Getestet sind JPEG und PNG.
files	ja (mehrere Seiten)	Das Feld je Seite wiederholen, um ein mehrseitiges Ergebnis zu erhalten.

Der Endpunkt ist POST https://api.scankit.io/scan/crop und nimmt multipart/form-data an. Senden Sie entweder file oder files, nie beides.

Authentifizierung: Header X-API-Key (empfohlen), Authorization: Bearer YOUR_API_KEY oder der Query-Parameter api_key.
Nur Bilder. Ein PDF-Upload wird mit 502 und einem Dekodierfehler beantwortet; PDF ist hier ein Ausgabeformat, keine Eingabe.
Ein Credit pro Seite. Zwei Seiten in einer Anfrage kosten zwei Credits.

Parameter

Parameter	Standard	Funktion
output_width	1536	Breite des zurückgegebenen Bildes in Pixeln.
filter	white	white bereinigt den Hintergrund, flat erhält die Textur, original ändert nichts.
version	2	Verarbeitungs-Pipeline. 2 ist die aktuelle.
binary	true	true liefert die Bilddaten, false verpackt das Ergebnis in JSON.
strip_black_border	true	Entfernt schwarze Ränder um die erkannte Seite.
return_pdf	false	Liefert ein PDF statt eines Bildes.
return_meta	false	Ergänzt die Erkennungs-Metadaten in der JSON-Antwort (mit binary=false) und lässt die Pipeline das Erkennungsergebnis auf dem Bildpfad melden, wo es als Header X-ScanKit-Detected zurückkommt.
return_warp_geometry	false	Liefert die Geometrie der erkannten Seite statt eines Bildes.
segment_count	12	Anzahl der Raster-Segmente in der v2-Pipeline. Muss eine ganze Zahl sein.
ocr_lang	eng	Sprachhinweis für die Textebene der PDF-Ausgabe.

Zwei Parameter, die sich ausschließen

return_pdf und return_warp_geometry lassen sich nicht kombinieren: Der Geometrie-Modus liefert Koordinaten, kein Bild. Die API antwortet mit 400, statt zu raten.

json

{
  "error": "return_warp_geometry cannot be combined with return_pdf (geometry mode returns no image)"
}

Wenn kein Dokument gefunden wird

Eine verpasste Erkennung ist kein Fehler. Die Anfrage antwortet mit 200 und liefert das gesendete Bild unverändert zurück; ein Client, der nur den Statuscode prüft, kann Scan und Fehlschlag nicht unterscheiden. Fragen Sie das Erkennungsmerkmal ab und prüfen Sie es.

Signal	Wo es erscheint	Werte
document_detected	JSON-Antwort (binary=false, dazu return_meta=true oder return_warp_geometry=true)	true: ein Dokument wurde erkannt und entzerrt. false: es wurde kein nutzbares Dokument modelliert, das Bild ist die unveränderte Eingabe. null: die Pipeline hat ohne Erkennungsergebnis geantwortet.
X-ScanKit-Detected	Antwort-Header auf dem Bildpfad (return_meta=true senden)	true oder false. Fehlt, wenn die Pipeline kein Erkennungsergebnis gemeldet hat.

json

{
  "success": true,
  "document_detected": false,
  "image_base64": "<the unchanged input image>"
}

Bei false ist die übliche Behandlung, dem Nutzer das Foto mit einer manuellen Zuschnitt-Ansicht zurückzugeben oder um ein besseres Foto zu bitten: ganze Seite im Bild, gleichmäßiges Licht, kein harter Schatten über der Kante. ScanKit erfindet keinen Zuschnitt für ein Dokument, das es nicht gefunden hat.

Beispiele

Erster Aufruf, Bild hinein und Bild heraus:

bash

curl -X POST "https://api.scankit.io/scan/crop" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@document.jpg" \
  -F "output_width=1536" \
  -F "filter=white" \
  -o scan.jpg

Derselbe Aufruf in Python, diesmal mit PDF als Ausgabe:

python

import requests

with open("document.jpg", "rb") as fh:
    response = requests.post(
        "https://api.scankit.io/scan/crop",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"file": ("document.jpg", fh, "image/jpeg")},
        data={"return_pdf": "true"},
        timeout=60,
    )

response.raise_for_status()
with open("scan.pdf", "wb") as out:
    out.write(response.content)

Zwei Seiten in einer Anfrage, ein PDF zurück:

bash

curl -X POST "https://api.scankit.io/scan/crop" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@page-1.jpg" \
  -F "files=@page-2.jpg" \
  -F "return_pdf=true" \
  -o scan.pdf

Fehler

Status	Bedeutung	Was zu tun ist
400	Ungültiger Parameter oder keine Datei	output_width und segment_count müssen ganze Zahlen sein, und die Anfrage braucht file oder files.
401	Missing API Key	Header X-API-Key senden. Prüfen Sie auf ein Leerzeichen am Ende des Schlüssels.
401	Invalid API Key	Der Schlüssel wurde gesendet, gehört aber zu keinem aktiven Konto.
402	Insufficient credits	Credits im Dashboard aufladen.
429	Rate Limit	Die in Retry-After genannten Sekunden abwarten, dann erneut senden.
502	Das Bild konnte nicht verarbeitet werden	Ein nicht unterstütztes oder beschädigtes Bild oder eine Erkennung, die in der Pipeline fehlschlägt. Eine verpasste Erkennung muss keinen Fehler ergeben: siehe "Wenn kein Dokument gefunden wird".

json

{ "errors": [ { "title": "Invalid API Key" } ] }

Eine abgelehnte Anfrage kostet nichts: Nur ein Aufruf mit Ergebnis verbraucht Credits. Ein fehlgeschlagener Durchlauf lässt sich also ohne doppelte Kosten wiederholen.

Wie es weitergeht

Schnellstart mit Copy-Paste-Code

Konto, API-Schlüssel und ein erster Scan in fünf Minuten.

Zum Schnellstart

Texterkennung

Dasselbe Foto, aber mit dem erkannten Text statt eines Bildes.

Zu extract_text

Auf dieser Seite

Anfragevertrag
Parameter
Wenn kein Dokument gefunden wird
Beispiele
Fehler
Wie es weitergeht

Dokumentation