← Back to blog

PDF to Images API: Render Pages to PNG for Vision Models

October 27, 2026 · Eric · 7 min read

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.

What the endpoints actually do

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.

EndpointAuthInputReturns
POST /api/agent/pdf-to-imagesAgent key (Bearer)multipart pdf, optional formatimages[] with base64 data, mime, size, filename
POST /api/agent/images-to-pdfAgent key (Bearer)multipart images (repeatable)downloadUrl, filename, pages, size
POST /api/pdf-to-imagesBrowser sessionmultipart pdffiles[] with downloadUrl per page
POST /api/images-to-pdfBrowser sessionmultipart imagesdownloadUrl, 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.

Step 1: Render a PDF to PNG with curl

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.

Step 2: The same thing in Python

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"])

Step 3: Hand a page to a vision model

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.

Design tip

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.

Step 4: Go the other way — images into a PDF

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:

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.

Limits, error codes, and where pipelines break

This is the part that decides whether your batch job survives a Tuesday. All of these come from the implementation:

ConstraintValue
PDF upload size75 MB
Render resolution150 DPI, fixed
Render timeout60 seconds
Inline image budget per response20 MB of generated PNG/JPEG
Images per images-to-pdf call50, 25 MB each, 250 MB total
Daily request limit25/day on a free agent key, 1000/day on Pro

The errors you should branch on:

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.

When this is the wrong tool

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.

A realistic end-to-end shape

  1. Receive a PDF (email attachment, upload, signed URL).
  2. Try pdf-to-markdown for the text layer.
  3. If the text is empty or nonsense, rasterize with pdf-to-images.
  4. Send only the ambiguous pages to describe-image.
  5. Assemble the result, then rebuild a deliverable with 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.

Try it in the Toolbox

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 toolbox

Related: PDF Processing API for Agents · Video Processing APIs · Free OCR API