Resizing one image is a solved problem. Resizing a hundred of them — with the exact same framing, the exact same quality setting, and filenames that sort correctly when they land in a CMS — is where scripts get ugly and browser tabs multiply.
Agent Media Tools ships a batch endpoint that takes the boring part seriously: POST /api/batch-process-images accepts up to 20 files in a single multipart request, applies one operation (resize, convert, or compress) to every file, and returns JSON listing each output plus a ZIP of the whole run. This post is the working reference: parameters that actually matter, curl and Python you can paste, and the limits you should design around before your first production run.
Drop images into the Batch process panel in the toolbox, or use the purpose-built Product Image Studio for marketplace-ready batches with saved settings.
Open Product Image StudioOne request equals one operation applied uniformly. You are not passing per-file instructions — you are passing a shared recipe and a pile of files. That constraint is the feature: it makes runs predictable, comparable, and cheap to reason about.
| Property | Verified behavior |
|---|---|
| Endpoint | POST https://agentmediatools.com/api/batch-process-images |
| Input field | images (repeatable, multipart/form-data) |
| File count | 1–20 per request |
Operations (sub) | resize (default), convert, compress |
| Geometry | width, height (1–8000 px), fit = cover | inside | contain, background (#rrggbb) |
| Encoding | format, quality (default 85) |
| Naming | prefix (letters, digits, dash, underscore; 40 chars max) |
| Response | files[] with per-file downloadUrl, plus totalFiles, totalSize, zipUrl |
Uploads are temporary: the server deletes each inbound file right after it writes the output. Outputs and the ZIP live under /downloads/ and are swept by a cleanup job, so treat the URLs as short-lived — download within the same job that created them.
sub=resize is the workhorse. Give it a width, a height, or both, and choose how the image should fit that box:
fit | Result | Use it when |
|---|---|---|
cover | Fills the box, crops the overflow | Card grids and thumbnails where edges don't matter |
inside | Fits entirely within the box, no padding | You want the whole image and varied output sizes are fine |
contain | Fits entirely within the box, pads the rest with background | Product shots that must be uniformly sized and uncropped |
Two details that regularly surprise people:
maintainAspect=true is shorthand for fit=inside. If you also send fit, the explicit fit value wins — so don't send both and hope.For uniform product tiles, fit=contain with a background that matches your storefront is the combination that produces the boring, consistent grid buyers expect:
curl -X POST https://agentmediatools.com/api/batch-process-images \ -H "Authorization: Bearer mt_your_key_here" \ -F "images=@red-shoe-1.jpg" \ -F "images=@red-shoe-2.jpg" \ -F "images=@red-shoe-3.jpg" \ -F "sub=resize" \ -F "width=1200" \ -F "height=1200" \ -F "fit=contain" \ -F "background=#f4f1ec" \ -F "prefix=summer-sale-2026" \ -F "format=webp" \ -F "quality=82"
The real response shape (values shortened):
{
"success": true,
"files": [
{
"index": 1,
"originalName": "red-shoe-1.jpg",
"filename": "summer-sale-2026-01-red-shoe-1.webp",
"size": 184233,
"downloadUrl": "/downloads/batch-8f2c.../summer-sale-2026-01-red-shoe-1.webp"
}
],
"totalFiles": 3,
"totalSize": 552699,
"zipUrl": "/downloads/batch-8f2c....zip"
}
Note that downloadUrl and zipUrl are root-relative. Prefix them with https://agentmediatools.com before handing them to another service, or the link resolves against your own host.
sub=convert rewrites every file to one target format and skips the resize step entirely — no geometry parameters are read. Supported targets are jpeg, png, webp, avif, and tiff; anything else returns 400 with Unsupported format: … before a single file is processed.
curl -X POST https://agentmediatools.com/api/batch-process-images \ -H "Authorization: Bearer mt_your_key_here" \ -F "images=@hero.png" \ -F "images=@detail.png" \ -F "sub=convert" \ -F "format=webp" \ -F "quality=80"
Conversion is the cheapest way to cut payload on a site that still stores PNGs. It is also the operation where PNG output ignores quality — PNG is lossless, so the encoder just does its best.
sub=compress keeps pixel dimensions and original format, and spends quality instead. JPEG, WebP, AVIF, and TIFF honor the value; PNG is written at maximum compression regardless. This is the operation to reach for when a client emails "these photos are 8 MB each and the site is slow" and nobody is allowed to change the layout.
curl -X POST https://agentmediatools.com/api/batch-process-images \ -H "Authorization: Bearer mt_your_key_here" \ -F "images=@dsc_0101.jpg" \ -F "images=@dsc_0102.jpg" \ -F "sub=compress" \ -F "quality=60"
requests handles repeated images fields natively — pass a list of tuples and it writes the multipart body for you. This script takes the first 20 JPEGs in a directory, sends one recipe, and saves the ZIP:
import pathlib
import requests
API = "https://agentmediatools.com/api/batch-process-images"
KEY = "mt_your_key_here" # omit the header entirely for anonymous use
paths = sorted(pathlib.Path("catalog").glob("*.jpg"))[:20]
handles = [p.open("rb") for p in paths]
try:
files = [("images", (p.name, h, "image/jpeg")) for p, h in zip(paths, handles)]
r = requests.post(
API,
headers={"Authorization": f"Bearer {KEY}"},
files=files,
data={
"sub": "resize",
"width": "1200",
"height": "1200",
"fit": "contain",
"background": "#f4f1ec",
"format": "webp",
"quality": "82",
"prefix": "catalog",
},
timeout=300,
)
r.raise_for_status()
job = r.json()
print(job["totalFiles"], "files,", round(job["totalSize"] / 1048576, 2), "MB")
zip_url = "https://agentmediatools.com" + job["zipUrl"]
pathlib.Path("catalog-1200.zip").write_bytes(
requests.get(zip_url, timeout=120).content
)
finally:
for h in handles:
h.close()
Two production notes. First, do the ZIP download in the same run — the files are temporary. Second, if you are uploading more than 20 files, chunk the list and let each chunk be its own request rather than fighting the limit.
Naming differs by operation, and the resize behavior depends on whether you sent a prefix. These are the real generated names:
| Request | Output filename |
|---|---|
resize, no prefix, input Red Shoe (front).JPG | resized-1-Red Shoe (front).webp |
resize, prefix=summer sale 2026!!, input IMG 0042.png | summer-sale-2026-07-IMG-0042.jpg |
convert, input hero.png | converted-2-hero.webp |
compress, input dsc_0101.jpg | compressed-1-dsc_0101.jpg |
Without a prefix you inherit the original filename, spaces and parentheses included — fine for a download, annoying in a URL. With a prefix, the server slugifies it (spaces and punctuation become dashes, capped at 40 characters) and inserts a zero-padded index, which gives you deterministic sort order. The prefix applies to resize only; convert and compress use their own fixed patterns.
| Constraint | Value |
|---|---|
| Images per request | 20 |
| Size per file | 25 MB |
| Combined upload | 200 MB |
| Width / height | 1–8000 px |
| Output retention | ~20 minutes, cleaned up automatically |
| Daily allowance | 10/day anonymous per IP · 25/day free account · 25/day free agent key · 1,000/day Pro |
Error responses are explicit, which makes retry logic easy to write:
400 — At least one image required, Maximum 20 images per batch, Width or height must be between 1 and 8000 pixels, or Unsupported format.413 with code UPLOAD_TOTAL_TOO_LARGE — the combined upload exceeded the cap. Split the batch.429 — daily limit reached; the body names the limit and the upgrade path (ANON_DAILY_LIMIT, FREE_USER_DAILY_LIMIT, AGENT_FREE_DAILY_LIMIT, PAID_DAILY_LIMIT).500 with code BATCH_IMAGE_FAILED — one file could not be decoded or written; retry the batch without the offending file.One accounting detail worth knowing before you plan capacity: signed-in accounts have each image in a batch counted toward the daily limit, because a 20-file run is genuinely 20 images of work. Anonymous requests are counted once per request, and agent keys are counted once per request against the key's daily limit.
The endpoint is part of the public tool surface, so it accepts three kinds of callers:
Authorization: Bearer mt_…) — create one in your account. This is the right choice for scripts and agents; the key's daily limit applies and no CSRF token is needed.Origin header, or the request is rejected as cross-site.Honest boundaries, so you don't build around the wrong tool:
resize_image, convert_image, and compress_image one file at a time; there is no batch MCP tool, so an agent that needs batches should call this REST endpoint directly or loop the single-file tools.Filter inputs first — drop anything under your target resolution so you don't upscale, and drop anything over 25 MB.
Chunk into groups of 20, keeping the combined size under 200 MB per chunk.
Send one request per chunk with a prefix that identifies the run, then download each zipUrl in the same job.
Log totalFiles and totalSize per chunk so a silent partial run shows up as a mismatch instead of a mystery.
That's the whole contract: files in, one recipe, JSON plus a ZIP out, twenty minutes to collect your work. For a repeatable ecommerce workflow with saved settings, the Product Image Studio wraps the same endpoint in a UI; for everything else, the endpoint is one HTTP call away.
Run the same tools in the browser, or call them from your agent with an API key.
Open toolbox