Home/Documentation/POST /scan/crop
Endpoint reference

POST /scan/crop

Send one document photo, get back a clean, straight, tightly cropped scan. This is the endpoint behind the quickstart and the one almost every integration uses first.

Request contract

FieldRequiredWhat it does
fileyes (single page)One image as multipart form data. JPEG and PNG are the tested formats.
filesyes (multi page)Repeat the field once per page to get one multi-page result.

The endpoint is POST https://api.scankit.io/scan/crop and takes multipart/form-data. Send either file or files, never both.

  • Authentication: X-API-Key header (recommended), Authorization: Bearer YOUR_API_KEY or the api_key query parameter.
  • Images only. A PDF upload is answered with 502 and a decode error; PDF is an output format here, not an input.
  • One credit per page. Two pages in one request cost two credits.

Parameters

ParameterDefaultWhat it does
output_width1536Width of the returned image in pixels.
filterwhitewhite cleans the background, flat keeps the texture, original changes nothing.
version2Processing pipeline. 2 is the current one.
binarytruetrue returns the image bytes, false wraps the result in JSON.
strip_black_bordertrueRemoves black borders around the detected page.
return_pdffalseReturns one PDF instead of an image.
return_metafalseWith binary=false, adds detection metadata to the JSON response.
return_warp_geometryfalseReturns the geometry of the detected page instead of an image.
segment_count12Number of grid segments used by the v2 pipeline. Must be an integer.
ocr_langengLanguage hint for the text layer of the PDF output.
Two parameters that exclude each other
return_pdf and return_warp_geometry cannot be combined: geometry mode returns coordinates, not an image. The API answers 400 instead of guessing.
json
{
  "error": "return_warp_geometry cannot be combined with return_pdf (geometry mode returns no image)"
}

Examples

First call, image in and image out:

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

The same call in Python, asking for a PDF:

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)

Two pages in one request, one PDF back:

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

Errors

StatusMeaningWhat to do
400Invalid parameter or no fileoutput_width and segment_count must be integers, and the request needs file or files.
401Missing API KeySend the X-API-Key header. Check for a trailing space in the key.
401Invalid API KeyThe key was sent but belongs to no active account.
402Insufficient creditsTop up credits in the dashboard.
429Rate limitWait for the seconds given in Retry-After, then retry.
502The image could not be processedUsually no document was found, or the upload was not a supported image format.
json
{ "errors": [ { "title": "Invalid API Key" } ] }

A refused request costs nothing: only a call that produced a result consumes credits. That is why a failed batch can be retried without paying twice.

Next steps

Quickstart with copy-paste code
Account, API key and a first scan in five minutes.
Open the quickstart
Text extraction
The same photo, but with the recognised text back instead of an image.
To extract_text
Documentation