Scanned documents and images (OCR)

Not every document contains text: a scan, a fax or a photo of an invoice is just a picture. DocSlice reads these with OCR (optical character recognition) automatically; you do not choose it and you call the same endpoint.

When OCR is used

• You send an image: PNG, JPG, JPEG, WEBP, TIFF or BMP.
• You send a PDF with little or no text, typically a scan.

A PDF with real text is read directly and quickly, without OCR. The answer always tells you what happened with ocr_applied.

curl -s https://api.docslice.app/v1/convert \
  -H "Authorization: Bearer $DOCSLICE_API_KEY" \
  -F "file=@scan.jpg" \
  -F "format=json"
# the answer reports "ocr_applied": true for scans and photos

import json
import os
import requests

api_key = os.environ["DOCSLICE_API_KEY"]

with open("scan.jpg", "rb") as handle:
    response = requests.post(
        "https://api.docslice.app/v1/convert",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"file": ("scan.jpg", handle, "image/jpeg")},
        data={"format": "json"},
        timeout=180,
    )

result = response.json()
print("OCR used:", result.get("ocr_applied"))
print(json.dumps(result, indent=2))

const fs = require("node:fs");

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("scan.jpg")], { type: "image/jpeg" }), "scan.jpg");
form.append("format", "json");

fetch("https://api.docslice.app/v1/convert", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.DOCSLICE_API_KEY}` },
  body: form,
})
  .then((response) => response.json())
  .then((result) => {
    console.log("OCR used:", result.ocr_applied);
    console.log(JSON.stringify(result, null, 2));
  });

<?php
$curl = curl_init('https://api.docslice.app/v1/convert');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DOCSLICE_API_KEY')],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('scan.jpg', 'image/jpeg', 'scan.jpg'),
        'format' => 'json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 180,
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);
echo 'OCR used: ' . var_export($result['ocr_applied'] ?? null, true) . PHP_EOL;
echo json_encode($result, JSON_PRETTY_PRINT);

What it costs in pages

OCR pages count like every other page: a 3-page scanned PDF uses 3 pages of your monthly quota, the same as a 3-page digital PDF. There is no separate allowance. See Usage and quota.

When the OCR provider does not answer

OCR relies on an external provider, and what happens when it does not answer depends on what you sent:

• An image (PNG, JPG, JPEG, WEBP, TIFF, BMP) cannot be read without OCR. The request fails with 503 and a Retry-After: 60 header, and no pages are charged for that attempt. Wait the indicated time and retry; the example in Rate limits shows a retry loop.
• A scanned PDF falls back to the text the PDF itself contains, which for a real scan is little or nothing. The request still succeeds (200) with ocr_applied: false and whatever text could be read. Always check ocr_applied when you send scans: if it is false and data looks empty, send the document again later.

Getting good results

• Send the best source you have: the original PDF or a straight, well-lit photo beats a photo of a screen.
• Aim for a resolution that keeps small print readable; very large files are limited to 50 MB.
• Straighten and crop photos when you can, and avoid shadows across the text.
• Combine OCR with a schema to get only the fields you need from a scan.

Supported files and size limits are listed in Formats and limits.