Every squashed profile photo on the web comes from the same mistake: taking a 4000×3000 camera image, asking for 1080×1080, and letting the library stretch it. The fix is not a better camera or a designer — it is choosing the right fit behavior for the job.
The resize endpoint on Agent Media Tools accepts the same fit values as
Sharp underneath, which means you can crop-to-fill, fit-without-cropping, or
stretch on purpose. This guide covers all three, plus the crop endpoint for
exact framing and the batch endpoint for padding batches of product photos
with a real background color. Every example below hits endpoints that exist
in production today, with real parameter names.
POST /api/resize-image reads width, height,
fit, format, quality, and
maintainAspect. When you supply both dimensions and nothing else,
it defaults to cover.
| Mode | What happens | Use it for |
|---|---|---|
cover (default) |
Scales until both dimensions are met, then center-crops the overflow. | Avatars, cards, thumbnails — any fixed frame. |
inside |
Scales until the image fits, never crops, so one side comes out smaller. | Previews, email images, anywhere the whole frame matters. |
fill |
Stretches to the exact box, changing the aspect ratio. | Gradients, textures, abstract art. Not faces. |
You do not pass fit=inside directly on every call: sending
maintainAspect=true is the documented switch for it, and it takes
priority over whatever fit value you send. That is a detail worth
knowing, because a request with maintainAspect=true&fit=cover
behaves like inside, not cover.
Take a 4000×3000 photo and ask for a 1080×1080 card image:
curl -X POST https://agentmediatools.com/api/resize-image \ -F "image=@photo.jpg" \ -F "width=1080" \ -F "height=1080" \ -F "fit=cover" \ -F "format=webp" \ -F "quality=82"
The response is a small JSON object with a relative download path:
{
"success": true,
"filename": "8f3c1a2b9d.webp",
"filesize": 184233,
"downloadUrl": "/downloads/8f3c1a2b9d.webp"
}
The math behind the output: cover scales by the larger ratio, so
4000×3000 becomes 1440×1080 and then loses about 360 pixels from each side.
Nobody gets thinner, and the subject stays centered. If your subject is not
centered, cover is the wrong tool — jump to the crop section.
Note the shape of the API: this is a multipart POST with the file
in an image field. There is no query-string variant that takes an
image URL on this endpoint.
For a blog hero or an email header you usually cannot afford to lose the edges of the frame. Flip the aspect switch:
curl -X POST https://agentmediatools.com/api/resize-image \ -F "image=@photo.jpg" \ -F "width=1080" \ -F "height=1080" \ -F "maintainAspect=true" \ -F "format=webp"
The same 4000×3000 input now comes back as 1080×810. The full
frame survives, the width hits the target, and the height lands wherever the
aspect ratio puts it. In CSS terms this is object-fit: contain
without the letterbox bars — the canvas shrinks to the content instead of
padding it.
That difference matters when you are generating markup. If your template
assumes a 1080×1080 box, inside output will leave a gap; if your
template sizes to the image, inside is the safe default.
curl -X POST https://agentmediatools.com/api/resize-image \ -F "image=@noise-texture.png" \ -F "width=512" \ -F "height=512" \ -F "fit=fill" \ -F "format=png"
fill ignores the source ratio entirely. On a gradient or a noise
texture you will never notice. On a 3:4 portrait pushed into 16:9 you get the
classic wide-face problem that started this article. Treat it as a deliberate
choice for flat art, not a fallback.
When the subject sits off-center, resizing cannot save you. You need to say
where the window goes. POST /api/crop-image takes
left, top, width, and
height in source pixels and always writes a PNG.
curl -X POST https://agentmediatools.com/api/crop-image \ -F "image=@photo.jpg" \ -F "left=420" \ -F "top=0" \ -F "width=1080" \ -F "height=1080"
That example turns a 1920×1080 screenshot into a centered square: the crop
width equals the source height, and the leftover
1920 − 1080 = 840 pixels split evenly into
left=420. The response is JSON with
filename, downloadUrl, and size, so you
fetch the result in a second request.
Center-crop offsets are worth computing rather than hardcoding, because the same code then works for any source size:
def center_crop(w, h, target_w, target_h):
# shrink the larger axis until the ratio matches, never upscale
if w / h > target_w / target_h:
crop_w, crop_h = int(h * target_w / target_h), h
else:
crop_w, crop_h = w, int(w * target_h / target_w)
return (w - crop_w) // 2, (h - crop_h) // 2, crop_w, crop_h
print(center_crop(1920, 1080, 1, 1)) # (420, 0, 1080, 1080)
One honest limit: you cannot crop a 16:9 frame into 4:5 without inventing
pixels. The tallest 4:5 slice of a 1920×1080 image is 864×1080, so the choice
is a tighter crop (left=528, width=864) or padding
the canvas. That is the next section.
POST /api/batch-process-images accepts up to 20 files in an
images field and supports three modes:
sub=resize, sub=convert, and
sub=compress. Unlike the single-image endpoint, the resize mode
also accepts fit=contain plus a hex background, which
is how you get letterboxing with a color you control (white by default), and a
prefix for predictable filenames.
curl -X POST https://agentmediatools.com/api/batch-process-images \ -F "images=@front.jpg" \ -F "images=@side.jpg" \ -F "images=@detail.jpg" \ -F "sub=resize" \ -F "width=1200" \ -F "height=1200" \ -F "fit=contain" \ -F "background=#f7f5f0" \ -F "prefix=catalog" \ -F "format=webp" \ -F "quality=80"
Every file comes back described individually, plus a ZIP of the whole batch:
{
"success": true,
"files": [
{ "index": 1, "originalName": "front.jpg", "filename": "catalog-01-front.webp",
"size": 96411, "downloadUrl": "/downloads/batch-9d1c/catalog-01-front.webp" }
],
"totalFiles": 3,
"totalSize": 288744,
"zipUrl": "/downloads/batch-9d1c.zip"
}
Two hard limits are enforced in the route: a maximum of 20 images per request and 200 MB of uploaded bytes total. In resize mode, width and height must be between 1 and 8000 pixels. Inputs are multipart files — the batch endpoint does not fetch remote URLs for you, so download first if your images live on a CDN.
import io, zipfile, requests
BASE = "https://agentmediatools.com"
files = [
("images", ("front.jpg", open("front.jpg", "rb"), "image/jpeg")),
("images", ("side.jpg", open("side.jpg", "rb"), "image/jpeg")),
]
data = {
"sub": "resize",
"width": "1200",
"height": "1200",
"fit": "contain",
"background": "#f7f5f0",
"prefix": "catalog",
"format": "webp",
"quality": "80",
}
r = requests.post(f"{BASE}/api/batch-process-images", files=files, data=data, timeout=180)
r.raise_for_status()
batch = r.json()
zip_bytes = requests.get(BASE + batch["zipUrl"], timeout=120).content
with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
zf.extractall("out/")
print(len(zf.namelist()), "files extracted")
Keep the files list and the data dict separate:
everything except the images is a plain form field, which is why the numbers
are strings here.
The MCP server exposes resize_image, which takes a public
image_url plus width, height,
format, and quality, downloads the file server-side,
and calls the same resize route. That is the convenient path when the agent
already has a URL instead of a local file:
{
"tool": "resize_image",
"arguments": {
"image_url": "https://example.com/photo.jpg",
"width": 1080,
"height": 1080,
"format": "webp",
"quality": 82
}
}
For crops with offsets, call /api/crop-image directly with
left and top; the MCP crop_image tool is
best used for simple width/height crops from a URL. If your agent needs the
cropped bytes inline instead of a download link, the agent-key variant
POST /api/agent/crop-image accepts url,
left, top, width, and
height and returns base64 PNG data with a usage block.
| Caller | Daily limit |
|---|---|
| Anonymous (per IP) | 10/day |
| Free account | 25/day |
| Free agent key | 25/day |
| Pro agent key | 1,000/day |
A batch request is one HTTP call, and anonymous callers are counted once against the 10/day gate. Signed-in users are metered per output file — a 20-image batch uses 20 of their 25 daily operations — so budget batches accordingly. The errors you will actually hit:
400 {"error":"Image required"} — the multipart field is missing or misnamed.400 {"error":"Specify width or height"} — neither dimension was sent.400 with a 1–8000 message — batch resize dimensions out of range.429 with ANON_DAILY_LIMIT or AGENT_FREE_DAILY_LIMIT — the response includes used, limit, and an upgrade link.
Fixed frame and centered subject: cover. Whole image must
survive: maintainAspect=true. Subject off-center: crop with
left/top. Whole batch needs a consistent canvas:
batch resize with fit=contain and a background.
Anything else is stretching a face.
Resize or crop an image in the browser, or call the same endpoints with an agent key.
Open toolboxPrefer a UI walkthrough? The resize image tool and the crop image tool expose these options as form fields, and the same routes are what the API calls under the hood.