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 | Mit binary=false ergänzt dies Erkennungs-Metadaten in der JSON-Antwort. |
| 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)"
}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.jpgDerselbe 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.pdfFehler
| 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 | Meist wurde kein Dokument gefunden oder die Datei ist kein unterstütztes Bildformat. |
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