← Back to blog

Crop Images via API: curl, Python, and Agent Keys

October 15, 2026 · Eric · 6 min read

Cropping is the least glamorous image operation and the one your pipeline hits most often. Product catalogs need a consistent square. Social cards need a 16:9 band off the top of a taller render. An agent that just generated a wide shot needs one region extracted before it hands the file to a human. Doing that locally means wiring Sharp, ImageMagick, or Pillow into whatever machine happens to be running the job.

This guide covers the two crop endpoints shipped by Agent Media Tools: a free multipart endpoint for a file you already have, and a Bearer-key endpoint for a public image URL. Both take exact pixel bounds and both return a PNG. Every request and field name below is taken from the running API, including the free-tier limits and the error codes you will actually see.

The two crop endpoints at a glance

 File uploadAgent (by URL)
EndpointPOST /api/crop-imagePOST /api/agent/crop-image
AuthNone (free daily gate), or an agent keyAuthorization: Bearer mt_…
Bodymultipart/form-dataJSON
Inputimage file, up to 25 MBurl (public, up to 20 MB)
Boundsleft, top, width, heightleft, top, width, height
ReturnsJSON with a downloadUrlJSON with base64 PNG data

Both hands-off to the same Sharp-based image pipeline that backs the resize and convert tools, so JPEG, PNG, and WebP inputs behave the way you expect. Output is always PNG.

1. Crop a local file with curl

The upload endpoint is a single multipart POST. Send the file as the image field and describe the region you want in pixels:

curl -s -X POST https://agentmediatools.com/api/crop-image \
  -F "image=@product-wide.jpg" \
  -F "left=120" -F "top=80" \
  -F "width=800" -F "height=800"

The response is JSON, not the image itself:

{
  "success": true,
  "filename": "k3f9c1a2.png",
  "downloadUrl": "/downloads/k3f9c1a2.png",
  "size": 284133
}

Fetch the output by prefixing the site origin, then keep or discard it:

URL=$(curl -s -X POST https://agentmediatools.com/api/crop-image \
  -F "image=@product-wide.jpg" \
  -F "left=120" -F "top=80" -F "width=800" -F "height=800" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['downloadUrl'])")

curl -s "https://agentmediatools.com${URL}" -o cropped.png
Field names

The offset fields are left and top. Some older snippets (and the bundled SDKs, which accept x/y convenience arguments) label them differently — when you call the REST API directly, use left and top or your offsets will be ignored and the crop will start at the top-left corner.

How the crop box behaves

2. Crop a public image by URL with an agent key

If the image already lives at a public URL, skip the download entirely. The agent endpoint fetches it server-side (30-second timeout, 20 MB limit) and returns the cropped region as base64 PNG:

curl -s -X POST https://agentmediatools.com/api/agent/crop-image \
  -H "Authorization: Bearer mt_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hero.png","left":0,"top":0,"width":1200,"height":630}'
{
  "success": true,
  "size": 318944,
  "mime": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUg...",
  "usage": { "used_today": 4, "limit": 25, "plan": "free" }
}

Decode it in one line with jq and base64:

curl -s -X POST https://agentmediatools.com/api/agent/crop-image \
  -H "Authorization: Bearer mt_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hero.png","width":1200,"height":630}' \
  | jq -r '.data' | base64 -d > hero-1200x630.png

Create keys from your account in the Toolbox; the same mt_ Bearer key works across the REST API and the hosted MCP connection.

3. Python with requests

For a local file, post the multipart body and follow the returned URL:

import requests

API = "https://agentmediatools.com/api/crop-image"

with open("product-wide.jpg", "rb") as fh:
    r = requests.post(
        API,
        files={"image": ("product-wide.jpg", fh, "image/jpeg")},
        data={"left": 120, "top": 80, "width": 800, "height": 800},
        timeout=60,
    )
r.raise_for_status()
payload = r.json()

print(payload["filename"], payload["size"])
img = requests.get("https://agentmediatools.com" + payload["downloadUrl"], timeout=60)
open("cropped.png", "wb").write(img.content)

For a remote URL, use the agent endpoint and write the decoded base64 directly to disk — no intermediate host, no temp file:

import base64, requests

r = requests.post(
    "https://agentmediatools.com/api/agent/crop-image",
    headers={"Authorization": "Bearer mt_YOUR_AGENT_KEY"},
    json={"url": "https://example.com/hero.png",
          "left": 0, "top": 0, "width": 1200, "height": 630},
    timeout=60,
)
r.raise_for_status()
data = r.json()

with open("hero-1200x630.png", "wb") as out:
    out.write(base64.b64decode(data["data"]))

print("used today:", data["usage"]["used_today"], "of", data["usage"]["limit"])

4. Free tier vs agent keys

CallerDaily allowanceNotes
Anonymous (per IP)10 calls/dayNo account, no key. Failed calls do not burn quota.
Free signed-in account25 calls/daySame endpoints, higher ceiling.
Agent key, free plan25 calls/dayUse it on /api/agent/crop-image or send it to the upload endpoint.
Agent key, Pro plan1,000 calls/dayDrops into usage credits once the daily allowance is spent.

Every request that returns a success status counts as one tool use, and the agent endpoint echoes your current usage in the usage block so a long-running job can throttle itself instead of discovering the limit through a 429.

5. Batch-crop a list of images

Because the URL endpoint takes JSON, a queue of crops is a plain loop:

import base64, pathlib, requests

KEY = "mt_YOUR_AGENT_KEY"
BOX = {"left": 0, "top": 0, "width": 1200, "height": 630}  # social card band

paths = pathlib.Path("out")
paths.mkdir(exist_ok=True)

for i, url in enumerate(open("urls.txt").read().split(), start=1):
    r = requests.post(
        "https://agentmediatools.com/api/agent/crop-image",
        headers={"Authorization": f"Bearer {KEY}"},
        json={"url": url, **BOX},
        timeout=90,
    )
    if r.status_code == 429:
        print("daily limit hit at item", i, r.json().get("error"))
        break
    r.raise_for_status()
    (paths / f"card-{i:04d}.png").write_bytes(base64.b64decode(r.json()["data"]))

Pair the loop with compression or the convert tool when the PNGs are heading for the web, and wire a webhook if a human needs to see the batch when it finishes.

6. Call it from an agent over MCP

The same crop is exposed to MCP clients as the crop_image tool, so an agent can crop without composing multipart requests. Point your client at the hosted MCP endpoint with your agent key and pass a public image URL plus the target size:

{
  "tool": "crop_image",
  "arguments": {
    "image_url": "https://example.com/hero.png",
    "width": 1200,
    "height": 630
  }
}

The tool fetches the image server-side and returns the cropped PNG; agents that need an offset region should use the REST endpoint above, where left and top are explicit. Tool names are the ones the server actually registers — crop_image, alongside resize_image and convert_image in the image group.

Errors you will actually hit

StatusResponseCause
400{"error":"Image required"}No image part in the multipart body.
400{"error":"url, width, height required"}Agent endpoint called without the URL or the target size.
500{"error":"Image crop failed.","code":"IMAGE_CROP_FAILED"}The requested box falls outside the source image, or the file is not a decodable image.
429{ "error": "Daily limit reached …" }Free or key allowance exhausted for the UTC day; the JSON includes upgrade and credit options.

What this API deliberately does not do

Honest boundaries save debugging time. The crop endpoints extract a rectangle and nothing else: there is no rotation, flip, or straightening parameter, and no aspect_ratio shortcut that fits a box for you — compute the four numbers you want and send them. Output is always PNG, so convert afterwards if a page needs JPEG or WebP. The interactive crop panel in the Toolbox edits on a canvas inside your browser, which is handy for eyeballing one image but is not the path to script; for repeatable work, use the endpoints above.

That is the whole tool. Four numbers in, one PNG out, from curl, from Python, or from an agent that never touches a filesystem.

Crop your first image in the browser

Open the crop tool to try exact pixel bounds, then grab the same endpoint with a free API key.

Open the crop tool