← Back to blog

Extract Text from PDFs and Images with a Free OCR API

Every developer hits the same wall: you have a scanned invoice, a photographed whiteboard, or an image-only PDF, and the text inside it is locked. Copy-paste fails. Your search index finds nothing. Your AI agent has nothing to summarize. Optical character recognition (OCR) is the standard fix, but standing up Tesseract, wrangling language packs, and keeping it reliable in production is a project of its own.

Agent Media Tools ships OCR as a plain HTTP endpoint: POST /api/ocr. Send a PDF or an image, get back the extracted text plus word and character counts. No SDK to install, no API key required for basic use, and the same endpoint is exposed as an MCP tool so your agent can call it directly.

In this guide you'll learn:

• How to extract text with a single curl command
• How to call the API from Python, including batch processing
• How the endpoint decides between PDF text extraction and image OCR
• How to wire it into an AI agent via the ocr_extract MCP tool

One endpoint, two extraction paths

The /api/ocr endpoint inspects what you send and picks the right engine automatically:

Input	Engine	Response field
PDF (text layer)	pdftotext with layout preserved; falls back to pdf-parse	engine: "pdftotext" or "pdf-parse"
Image (PNG, JPG, etc.)	Rasterized with Sharp, then tesseract	engine: "tesseract"

That split matters in practice. A digitally generated PDF already contains a text layer, so it extracts quickly and accurately without OCR. A scan — a photo of a printed page or a fax — has no text layer, so the endpoint runs real character recognition. You don't have to know which case you're in; the API figures it out from the file.

Every response includes the extracted text, the engine used, and word_count plus char_count, which are handy for token-budget estimates before you hand text to an LLM.

Quick start with curl

Upload a file directly with a multipart form. The field name is file:

curl -s -X POST https://agentmediatools.com/api/ocr \
  -F "file=@invoice-scan.png"

For a PDF, the same call works — the endpoint detects the %PDF- signature even if the filename is misleading:

curl -s -X POST https://agentmediatools.com/api/ocr \
  -F "file=@contract-2026.pdf"

You'll get back JSON:

{
  "success": true,
  "text": "INVOICE #1042\nAcme Consulting\n...",
  "engine": "tesseract",
  "word_count": 342,
  "char_count": 1891
}

No API key, no signup, no SDK — that's the whole call. You can also point the endpoint at a public URL instead of uploading, which is convenient when your file already lives somewhere reachable:

curl -s -X POST https://agentmediatools.com/api/ocr \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/scanned-contract.pdf"}'

The URL variant accepts url, image_url, or file_url in the JSON body, or a ?url= query parameter.

Python with requests

From Python, use requests and a file handle:

import requests

resp = requests.post(
    "https://agentmediatools.com/api/ocr",
    files={"file": open("receipt.jpg", "rb")},
)
data = resp.json()
print(data["text"])

For a URL-based call:

import requests

resp = requests.post(
    "https://agentmediatools.com/api/ocr",
    json={"url": "https://example.com/report.pdf"},
)
data = resp.json()
print(data["engine"], data["word_count"])

Batch processing a folder

When you have a directory of scans, parallelize with concurrent.futures and keep a small thread pool so you don't hammer the endpoint:

import concurrent.futures
from pathlib import Path
import requests

def ocr_file(path):
    with open(path, "rb") as f:
        r = requests.post(
            "https://agentmediatools.com/api/ocr",
            files={"file": f},
            timeout=120,
        )
    return path.name, r.json().get("text", "")

files = list(Path("scans").glob("*.png"))
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    for name, text in pool.map(ocr_file, files):
        Path("out").joinpath(name + ".txt").write_text(text)

That's a functional document-ingestion pipeline in under twenty lines — scan folder in, plain-text files out, ready for search indexing or an LLM.

Using OCR from an AI agent (MCP)

The same capability is exposed to MCP clients as the ocr_extract tool. It takes a single required argument, url, and returns the same JSON payload. Point your agent at the file and it gets the text back as tool output:

{
  "url": "https://example.com/scanned-contract.pdf"
}

Because the tool accepts a URL rather than local bytes, it fits naturally into agent workflows where the model has already staged a file somewhere public — for example, a document fetched by another tool, or a PDF generated earlier in the same pipeline. An agent can chain it: download an attachment, extract the text with ocr_extract, then summarize, classify, or route the content without a human in the loop.

Honest boundaries

OCR is impressive but not magic, and this endpoint is honest about its limits:

• Image OCR depends on the server's OCR engine. If Tesseract is not available on the deployment, image requests return a clear 501 error explaining that PDF text extraction still works. PDFs are the reliable path; test image OCR with a representative non-sensitive document before building a production dependency on it.
• Layout is preserved best for PDFs. The pdftotext path runs with layout mode, which keeps columns and spacing readable. Image OCR quality varies with scan quality, skew, and font.
• Extraction is not interpretation. OCR gives you the characters; it doesn't guarantee the document is authentic, complete, or correctly understood. Keep a human review step for consequential documents like contracts and medical records.

What else lives in the document toolkit

OCR is one step in a larger document pipeline. A few siblings worth knowing about:

• PDF to text (POST /api/pdf-to-text) — extracts the embedded text layer from a PDF without any OCR attempt, useful when you know the PDF is digital.
• PDF to Markdown (POST /api/pdf-to-markdown, MCP tool pdf_to_markdown) — converts PDF content to Markdown with structure intact, ideal for feeding documentation into an agent context window.
• Structured extract (POST /api/extract-structured) — lightweight regex-based heuristics for receipts and invoices (no LLM involved), returning fields rather than raw text.
• Document intake workflow — the document intake and OCR workflow page shows the full sequence: validate, normalize, extract, route.

Wrap-up

Extracting text from documents should be a utility, not a project. With POST /api/ocr you get PDF text extraction and image OCR behind one free endpoint, callable from curl, Python, or an MCP-connected agent — and the response includes word counts so you can budget tokens before the text ever reaches a model.

Start with a representative document from your own workflow, verify the extraction quality, and then connect the working path to your app or agent.

Related: PDF processing API · Pastebin API · Document intake OCR workflow · First-win templates