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.
| Route | Auth | Use it for |
|---|---|---|
POST /api/images-to-pdf | Session login (browser) | Human workflows, dashboard uploads, cookie-based scripts |
POST /api/agent/images-to-pdf | Authorization: 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.
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.
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.
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:
page-01.jpg, page-02.jpg, page-03.jpg — correct, zero-paddedpage-1.jpg, page-10.jpg, page-2.jpg — broken, this is the alphabetical trapinvoice-2026-09-p01.png, invoice-2026-09-p02.png — correct, and self-documentingIf 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.
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:
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.
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.
| Constraint | Value |
|---|---|
| Images per request | Up to 50 files in the images field |
| Size per image | 25 MB per uploaded file |
| Combined batch size | 250 MB total across all files |
| Auth | Session login (browser route) or mt_ bearer key (agent route) |
| Billing | Counts as one tool call against the account's daily allowance |
What each failure looks like:
400 — {"error":"Images required"}. The images field was empty or misspelled. Check the field name before anything else.401 — missing or invalid Authorization header on the agent route, or an expired session cookie on the browser route.413 — UPLOAD_TOTAL_TOO_LARGE. The combined upload exceeds 250 MB. Split the batch, or resize first — this is almost always a resizing problem, not a count problem.429 — daily limit reached. The body carries the limit and a usage object so you can read your own numbers instead of guessing: {"error":"Daily limit reached (N/day)...","usage":{"used":25,"limit":25,"plan":"free"}}. Free tooling tiers are deliberately small, so build a retry-after-UTC-midnight path rather than a retry loop.500 — IMAGES_TO_PDF_FAILED. Usually an image the assembler could not decode. Re-run the batch in halves to isolate it, then normalize that file through convert-image.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.
page-01.jpg, page-02.jpg, …
/api/agent/images-to-pdf and read pages plus downloadUrl from the response.
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.
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.
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