← Back to blog

Batch Image Processing API: Resize, Convert, and Compress 20 Images in One Call

October 23, 2026 · Eric · 7 min read

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.

Try it before you script it

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 Studio

What the batch endpoint actually does

One 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.

PropertyVerified behavior
EndpointPOST https://agentmediatools.com/api/batch-process-images
Input fieldimages (repeatable, multipart/form-data)
File count1–20 per request
Operations (sub)resize (default), convert, compress
Geometrywidth, height (1–8000 px), fit = cover | inside | contain, background (#rrggbb)
Encodingformat, quality (default 85)
Namingprefix (letters, digits, dash, underscore; 40 chars max)
Responsefiles[] 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.

Operation 1: resize a whole catalog to one box

sub=resize is the workhorse. Give it a width, a height, or both, and choose how the image should fit that box:

fitResultUse it when
coverFills the box, crops the overflowCard grids and thumbnails where edges don't matter
insideFits entirely within the box, no paddingYou want the whole image and varied output sizes are fine
containFits entirely within the box, pads the rest with backgroundProduct shots that must be uniformly sized and uncropped

Two details that regularly surprise people:

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.

Operation 2: convert formats in the same pass

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.

Operation 3: compress without touching dimensions

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"

Python: process a folder, then pull the ZIP

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.

Filenames: what you actually get back

Naming differs by operation, and the resize behavior depends on whether you sent a prefix. These are the real generated names:

RequestOutput filename
resize, no prefix, input Red Shoe (front).JPGresized-1-Red Shoe (front).webp
resize, prefix=summer sale 2026!!, input IMG 0042.pngsummer-sale-2026-07-IMG-0042.jpg
convert, input hero.pngconverted-2-hero.webp
compress, input dsc_0101.jpgcompressed-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.

Limits, errors, and what to design around

ConstraintValue
Images per request20
Size per file25 MB
Combined upload200 MB
Width / height1–8000 px
Output retention~20 minutes, cleaned up automatically
Daily allowance10/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:

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.

Authentication: keys for scripts, cookies for browsers

The endpoint is part of the public tool surface, so it accepts three kinds of callers:

When not to use this endpoint

Honest boundaries, so you don't build around the wrong tool:

The shape of a sane batch job

Step 1

Filter inputs first — drop anything under your target resolution so you don't upscale, and drop anything over 25 MB.

Step 2

Chunk into groups of 20, keeping the combined size under 200 MB per chunk.

Step 3

Send one request per chunk with a prefix that identifies the run, then download each zipUrl in the same job.

Step 4

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.

Try it in the Toolbox

Run the same tools in the browser, or call them from your agent with an API key.

Open toolbox