← Back to blog

Convert Images to PDF via API: Batch JPG and PNG Files Into One PDF

September 27, 2026 · Eric · 6 min read

Scans, screenshots, whiteboard photos, receipt captures, and images your agent just generated all end up needing the same boring deliverable: one PDF that a human can open, page through, and file. Doing that locally means pulling in an image library plus a PDF writer, wiring up page geometry by hand, and then discovering the pages are in the wrong order.

Agent Media Tools ships a single endpoint for exactly this job. You POST a multipart batch of images, it returns a PDF where each image is one full-bleed page, in a deterministic order. No local image stack, no PDF library, no page-size math.

This guide is written against the live code, not a roadmap. Every endpoint, parameter, limit, and error string below is the behavior you get today.

The two routes

RouteAuthUse it for
POST /api/images-to-pdfSession login (browser)Human workflows, dashboard uploads, cookie-based scripts
POST /api/agent/images-to-pdfAuthorization: Bearer mt_...Agents, cron jobs, and service-to-service automation

Both take the same multipart body and return the same JSON shape. The only difference is how you authenticate — and the agent route also reports your usage counters back to you.

Quick start: one curl call

The field name is images. Repeat it once per file:

curl -X POST https://agentmediatools.com/api/agent/images-to-pdf \
  -H "Authorization: Bearer mt_YOUR_KEY" \
  -F "images=@page-01.jpg" \
  -F "images=@page-02.png" \
  -F "images=@page-03.jpg"

Response:

{
  "success": true,
  "filename": "k3f9c1a7b2e4.pdf",
  "downloadUrl": "/downloads/k3f9c1a7b2e4.pdf",
  "pages": 3,
  "size": 482133,
  "usage": { "used_today": 12, "limit": 25, "plan": "free" }
}

Note that downloadUrl is a site-relative path. Prepend the host before you hand it to another service, and download the PDF before you finish the job — the file lives under /downloads/ on the same origin.

If you are scripting against the browser route instead of the agent route, send your session cookie with -b cookies.txt and drop the bearer header.

The same call from Python

With requests, the trick is that files must be a list of tuples when you repeat the same field name. A dict would silently keep only the last image:

import requests

API = "https://agentmediatools.com"
KEY = "mt_YOUR_KEY"

paths = ["page-01.jpg", "page-02.png", "page-03.jpg"]

files = [("images", (p.split("/")[-1], open(p, "rb"), "application/octet-stream")) for p in paths]

r = requests.post(
    f"{API}/api/agent/images-to-pdf",
    headers={"Authorization": f"Bearer {KEY}"},
    files=files,
    timeout=120,
)

r.raise_for_status()
data = r.json()

pdf = requests.get(f"{API}{data['downloadUrl']}", timeout=120)
with open("packet.pdf", "wb") as fh:
    fh.write(pdf.content)

print(data["pages"], data["size"], "bytes")

The timeout matters. A 40-image batch is not instant — image metadata is read for every file and each one is embedded into the growing PDF document before a single response is written. Give it room, and do not wrap it in a 10-second default client timeout.

Page order is filename order

This is the part that quietly ruins PDFs, so it is worth stating plainly: the endpoint sorts your uploaded files by original filename before building the document. Upload order is not preserved, and neither is the order of the -F flags on the command line.

That behavior is a feature once you use it. Name files so that a plain alphabetical sort matches the order you want:

If your source filenames come from a camera or a scanner (IMG_9931.JPG), prefix them with an index before sending. If they arrive from a queue with random UUIDs, you cannot control order through the API — rename on your side first.

Page geometry: one image, one page, no margins

Each image becomes its own page, and the page is sized to that image's pixel dimensions. There is no A4 letterboxing, no margin, and no automatic scaling to a standard paper size. A 4000×6000 photo becomes a 4000×6000 point page; a 1200×1600 scan becomes a 1200×1600 point page.

That is usually what you want for scans and screenshots, but it produces two predictable annoyances:

  1. Mixed page sizes. Mix a phone photo with a screenshot and your PDF viewer will resize between pages. Fix it upstream by normalizing every image to one width or one aspect ratio.
  2. Absurd file sizes. Full-resolution photos embedded at full resolution make a 60 MB PDF that nobody can email.

Both are solved with a resize pass before assembly. The image resize endpoint takes a multipart image, optional width / height, a maintainAspect flag, an output format, and a quality value:

curl -X POST https://agentmediatools.com/api/resize-image \
  -F "image=@scan-raw.jpg" \
  -F "width=1650" \
  -F "maintainAspect=true" \
  -F "format=jpeg" \
  -F "quality=82"

# {"success":true,"filename":"a91c....jpg","filesize":214552,
#  "downloadUrl":"/downloads/a91c....jpg"}

curl -o page-01.jpg https://agentmediatools.com/downloads/a91c....jpg

Run that over the batch, rename the results page-01, page-02, and so on, and the PDF comes out consistent in both page size and weight.

Format handling: PNG and JPEG are the happy path

The assembler inspects each file's detected format. PNG sources are embedded as PNG; everything else is handed to the JPEG embedder. In practice that means:

The image conversion endpoint handles that normalization, including a direct image-to-PDF mode:

# normalize a WebP screenshot into a PNG for assembly
curl -X POST https://agentmediatools.com/api/convert-image \
  -F "image=@screenshot.webp" \
  -F "format=png"

# or turn ONE image straight into a one-page PDF
curl -X POST https://agentmediatools.com/api/convert-image \
  -F "image=@receipt.jpg" \
  -F "format=pdf"
Formats accepted by format=jpeg, png, webp, avif, tiff, pdf

Rule of thumb: a single image going to a single PDF is a convert-image job. Two or more images that must become one multi-page document is an images-to-pdf job.

Limits and the errors you will actually hit

ConstraintValue
Images per requestUp to 50 files in the images field
Size per image25 MB per uploaded file
Combined batch size250 MB total across all files
AuthSession login (browser route) or mt_ bearer key (agent route)
BillingCounts as one tool call against the account's daily allowance

What each failure looks like:

An honest boundary: this is REST-only today

The toolbox exposes dozens of operations as MCP tools for Claude Desktop, Hermes, and other MCP clients — image resizing, cropping, compression, PDF merging, OCR, and form filling among them. Batch image assembly is not one of the MCP tools in the current server build.

If you are driving this from an agent, treat it as a plain HTTP call: one multipart POST, then download the returned path. Any agent runtime that can make an HTTP request with a header can do it, and it needs no extra glue.

Putting it together: a scan packets pipeline

Step 1
Collect and normalize. Pull the source images, resize each to a consistent width, write them to disk as page-01.jpg, page-02.jpg, …
Step 2
Assemble. POST the batch to /api/agent/images-to-pdf and read pages plus downloadUrl from the response.
Step 3
Verify. Assert pages equals the number of images you sent. If it does not, you dropped a file before the upload, and no amount of downstream handling will fix that.
Step 4
Deliver. Download the PDF and hand the bytes to your storage or delivery step. Keep the assembler and the delivery layer separate — the tool builds the document, your pipeline decides where it lives.

Related reading: the PDF processing API guide covers extraction, OCR, and form filling, and merge PDFs programmatically handles the case where your inputs are already PDFs instead of images.

Assemble a PDF from images right now

Drop your JPGs and PNGs into the browser tool, or call the same endpoint from your agent with an API key.

Open images to PDF