A PDF is not a picture. It is a compressed object graph of fonts, vectors, and text runs. Ask a vision model to "look at this invoice" and hand it a PDF byte stream, and you get garbage — the model sees no pixels because there are none in the format it was trained on. This is the quiet failure mode behind a lot of bad agent document workflows: the agent claims it read the document, but it only ever saw a filename.
The fix is boring and reliable: rasterize each page to a PNG, then send that image to a vision model. Agent Media Tools ships that as a REST endpoint — POST /api/agent/pdf-to-images — and its inverse, POST /api/agent/images-to-pdf, for stitching page bitmaps back into a document. This post covers the real request shapes, the response you actually get back, and the limits that decide whether your pipeline succeeds or returns a 413.
The server shells out to Poppler's pdftoppm at a fixed 150 DPI, then returns every page inline as base64. On a Letter-size page that lands around 1275 × 1650 pixels — dense enough for OCR and for small print, small enough that a single page rarely blows a request body budget.
| Endpoint | Auth | Input | Returns |
|---|---|---|---|
POST /api/agent/pdf-to-images | Agent key (Bearer) | multipart pdf, optional format | images[] with base64 data, mime, size, filename |
POST /api/agent/images-to-pdf | Agent key (Bearer) | multipart images (repeatable) | downloadUrl, filename, pages, size |
POST /api/pdf-to-images | Browser session | multipart pdf | files[] with downloadUrl per page |
POST /api/images-to-pdf | Browser session | multipart images | downloadUrl, pages |
Notice the split personality. The browser endpoints write files to disk and hand you links under /downloads/. The agent endpoints return raw base64 so a model-driven client never needs a second authenticated fetch. That difference matters more than it looks: an agent holding only an API key cannot load a session-protected download link, so the base64 variant is the one you want in automation.
Grab a key from the Toolbox (keys look like mt_...) and export it. Then one request returns every page:
export AMT_KEY="mt_your_key_here" curl -s -X POST https://agentmediatools.com/api/agent/pdf-to-images \ -H "Authorization: Bearer $AMT_KEY" \ -F "pdf=@invoice.pdf" \ -F "format=png" \ -o pages.json
Inspect the envelope before you touch the payload:
jq '{pages, first: .images[0] | {filename, mime, size}, usage}' pages.json
You get something close to this — sizes and limits are live values from the response, not constants:
{
"pages": 3,
"first": {
"filename": "page-1.png",
"mime": "image/png",
"size": 214803
},
"usage": { "used_today": 4, "limit": 25, "plan": "free" }
}
Page numbering starts at 1 and follows document order. To pull just the first page out as a real file:
jq -r '.images[0].data' pages.json | base64 -d > page-1.png
Set format=jpeg when you are shipping pages to a model with a strict payload ceiling or when the source is photographic and you care about bytes more than crisp text edges. Any other value falls back to PNG, so do not expect webp to work here.
The loop below is the honest version: it checks the HTTP status, respects the response's own usage block, and writes each page only after decoding succeeds.
import base64
import os
import requests
API = "https://agentmediatools.com"
KEY = os.environ["AMT_KEY"]
with open("invoice.pdf", "rb") as handle:
response = requests.post(
f"{API}/api/agent/pdf-to-images",
headers={"Authorization": f"Bearer {KEY}"},
files={"pdf": ("invoice.pdf", handle, "application/pdf")},
data={"format": "png"},
timeout=120,
)
if response.status_code == 413:
raise SystemExit("Too many pixels for one response - split the PDF first.")
response.raise_for_status()
payload = response.json()
os.makedirs("pages", exist_ok=True)
for index, page in enumerate(payload["images"], start=1):
path = os.path.join("pages", f"page-{index:03d}.png")
with open(path, "wb") as out:
out.write(base64.b64decode(page["data"]))
print(path, page["size"], "bytes")
print("remaining today:", payload["usage"]["limit"] - payload["usage"]["used_today"])
Now the page is a PNG and the agent can actually see it. The companion endpoint is POST /api/describe-image, which accepts either a multipart image field (8 MB upload cap) or a hosted url in the body. Use task_type=query when you are asking a question — the default is plain captioning — and pass the question in prompt.
curl -s -X POST https://agentmediatools.com/api/describe-image \ -H "Authorization: Bearer $AMT_KEY" \ -F "image=@pages/page-001.png" \ -F "task_type=query" \ -F "prompt=What is the invoice total and due date?" | jq
One budget note worth internalizing before you build a 40-page pipeline: describe-image is billed at 2 flexible credits per call and does not draw on the free daily pool that the raster endpoints use. Rasterizing 40 pages is cheap; describing 40 pages is a real spend, so send the pages that matter — usually page 1, the signature page, or a table you already know exists — and route the rest to text extraction.
Decide per page, not per document. A mixed PDF (text cover page, scanned invoices, a photo appendix) is best handled by three different tools, and the raster endpoint is the escape hatch for the pages that defeat pdftotext.
Agents also need to produce documents. Screenshot a dashboard, stamp a receipt, collect five scanned pages, and someone eventually asks for "one PDF." Send the images as repeated images fields:
curl -s -X POST https://agentmediatools.com/api/agent/images-to-pdf \
-H "Authorization: Bearer $AMT_KEY" \
-F "images=@page-001.png" \
-F "images=@page-002.png" \
-F "images=@page-003.png" | jq '{pages, size, downloadUrl}'
Two behaviors are worth knowing because they are not obvious from the tool page:
page-10.png sorts before page-2.png. Zero-pad your names (page-001.png) and page order survives.The output is a temporary download link. Treat it as ephemeral: fetch and store the file yourself if it needs to outlive the session, the same way you would with any generated artifact.
This is the part that decides whether your batch job survives a Tuesday. All of these come from the implementation:
| Constraint | Value |
|---|---|
| PDF upload size | 75 MB |
| Render resolution | 150 DPI, fixed |
| Render timeout | 60 seconds |
| Inline image budget per response | 20 MB of generated PNG/JPEG |
Images per images-to-pdf call | 50, 25 MB each, 250 MB total |
| Daily request limit | 25/day on a free agent key, 1000/day on Pro |
The errors you should branch on:
413 with GENERATED_RESPONSE_TOO_LARGE — the rasterized pages exceeded the inline 20 MB budget. The PDF was small enough to accept but too heavy to return as base64. Split it and retry page ranges.500 with PDF_TO_IMAGES_FAILED — Poppler could not render, or the 60 second timeout hit. Password-protected and badly-encoded PDFs land here.429 — daily request limit reached. The body carries the reason and, if your key has usage credits, how many are available.400 — no file in the multipart body. Check that the field is literally named pdf (or images), not file.For the 413 case, split first with POST /api/split-pdf, which returns one PDF per page plus a dirId, then rasterize the pages you actually need. A 200-page catalog becomes twenty ten-page jobs instead of one guaranteed failure.
Rasterizing is lossy for text. If all you need is the words — search, summarization, RAG ingestion — POST /api/agent/pdf-to-text is the cheaper route (it counts against your daily request limit rather than credits), and POST /api/pdf-to-markdown is the one to reach for when you want layout-aware Markdown instead of a flat text dump. POST /api/ocr is the middle path for scanned pages where you want text but not an image to look at.
There is also a gap worth stating plainly: the MCP server exposes pdf_pages, merge_pdfs, pdf_to_markdown, pdf_form_fill, and ocr_extract, but page rasterization is a REST-only capability today. If your agent is MCP-only, it needs an HTTP call for this step — the endpoint takes a multipart body, which is exactly what MCP tool schemas handle badly.
pdf-to-markdown for the text layer.pdf-to-images.describe-image.images-to-pdf if the human wants a document back.That five-step chain handles almost every "the agent can't read this PDF" ticket, and every step is a single HTTP request you can retry independently — which is the property that makes document agents survive real traffic.
Drop a PDF on the PDF to Images page to see the pages render, or run the same call from your agent with an API key.
Open toolboxRelated: PDF Processing API for Agents · Video Processing APIs · Free OCR API