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.
| File upload | Agent (by URL) | |
|---|---|---|
| Endpoint | POST /api/crop-image | POST /api/agent/crop-image |
| Auth | None (free daily gate), or an agent key | Authorization: Bearer mt_… |
| Body | multipart/form-data | JSON |
| Input | image file, up to 25 MB | url (public, up to 20 MB) |
| Bounds | left, top, width, height | left, top, width, height |
| Returns | JSON with a downloadUrl | JSON 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.
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
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.
left and top are measured from the top-left corner of the source image, in pixels.width and height are the size of the extracted region. If you omit them, defaults are applied, so send them explicitly.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.
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"])
| Caller | Daily allowance | Notes |
|---|---|---|
| Anonymous (per IP) | 10 calls/day | No account, no key. Failed calls do not burn quota. |
| Free signed-in account | 25 calls/day | Same endpoints, higher ceiling. |
| Agent key, free plan | 25 calls/day | Use it on /api/agent/crop-image or send it to the upload endpoint. |
| Agent key, Pro plan | 1,000 calls/day | Drops 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.
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.
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.
| Status | Response | Cause |
|---|---|---|
| 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. |
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.
Open the crop tool to try exact pixel bounds, then grab the same endpoint with a free API key.
Open the crop tool