← Back to blog

Aspect Ratio Resizing API: Cover, Inside, and Fill

October 18, 2026 · Eric · 7 min read

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.

The three fit behaviors

POST /api/resize-image reads width, height, fit, format, quality, and maintainAspect. When you supply both dimensions and nothing else, it defaults to cover.

ModeWhat happensUse 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.

Step 1: square thumbnails with 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.

Step 2: inside when nothing may be cropped

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.

Step 3: fill is for textures, not portraits

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.

Step 4: exact framing with the crop endpoint

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.

Step 5: batch resize with real padding

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.

Step 6: the same batch from Python

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.

Step 7: let the agent do it

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.

Limits and error codes

CallerDaily limit
Anonymous (per IP)10/day
Free account25/day
Free agent key25/day
Pro agent key1,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:

Choosing in one line

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.

Try it in the Toolbox

Resize or crop an image in the browser, or call the same endpoints with an agent key.

Open toolbox

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