How to crop an image to a box or an aspect ratio with an API
Updated 2026-11-10
Use when an image must be cut to a box or to a given aspect ratio. Add output=url for a 24 h link.
From an MCP client, add https://tanod.dev/mcp and call image_crop; its free daily calls are applied automatically, no key or signup.
POST an image URL and either a box or an aspect ratio to /v1/image/crop. It returns the cropped image as base64 and the box that was applied.
Request
Give a box with left, top, width and height, or an aspect ratio such as 16:9 placed by gravity (center, a side such as north, or a corner such as northwest). Input is a public image URL (up to 10 MB) or image_base64 (up to 10 MB decoded; a data:image/...;base64, prefix is fine).
curl -s -X POST https://tanod.dev/v1/image/crop \
-H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
-d '{"url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg/gps/DSCN0010.jpg", "aspect": "16:9"}'The file comes back as base64 in the JSON. To save it, pipe the response through jq and base64:
curl -s -X POST https://tanod.dev/v1/image/crop \
-H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
-d '{"url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg/gps/DSCN0010.jpg", "aspect": "16:9"}' \
| jq -r '.data_base64' | base64 -d > cropped.jpgResponse
{
"operation": "crop",
"input": {
"format": "jpeg",
"width": 640,
"height": 480,
"bytes": 161713,
"frames": 1,
"animated": false,
"has_alpha": false
},
"source_url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg…",
"final_url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg…",
"format": "jpeg",
"content_type": "image/jpeg",
"bytes": 104465,
"width": 640,
"height": 360,
"data_base64": "/9j/4AAQSkZJRgAB",
"box": {
"left": 0,
"top": 60,
"width": 640,
"height": 360
},
"notes": [],
"source": {
"library": "Pillow",
"license": "MIT-CMU (HPND)",
"url": "https://python-pillow.org"
}
}Limits and caveats
Paying by card instead? The same image operations run as an Apify actor, Image Toolkit (tanod/image-toolkit), billed through your Apify account at USD 0.005 per image processed plus Apify's small start fee per run (failed images and invalid links are free). Give it a list of image links and one operation (resize, convert, compress, crop, rotate, thumbnail, watermark or strip metadata) and get the files back in the run's storage.
Bounds. A box outside the image is a 422 crop_out_of_bounds. Coordinates are in pixels of the image after EXIF orientation is applied.
Measured speed. In the 7 days to 13 October 2026, half of the 22 successful paid crops answered within 5.7 s and 95% within 9.2 s, measured end to end on our side (payment check, fetching the image from its URL, and the crop). Other image routes took about 2 to 2.6 s per paid call in the same week. Large images and slow hosts take longer, so allow about 15 s before timing out.
No face or subject detection. Aspect crops are positional and do not look for a subject, so check the result for portraits.
Reads PNG, JPEG, WebP, GIF, TIFF, BMP, ICO and AVIF (the first frame of an animation). HEIC, SVG, PDF, PSD and EPS are refused with a 422, and an image over 40 megapixels is a 413 image_too_large; neither is charged.
Metadata. EXIF, GPS, XMP and IPTC metadata are not carried into output images. Images and their metadata are processed for the answer and not logged; a result image is kept only when output is url, as a download file for 24 hours.
Doing this by hand? Use the free image cropper in your browser.
Download link. Add "output": "url" to the request and the file is stored for 24 hours and returned as a link (url, expires_at, sha256) instead of base64, which keeps it out of your context window. The price is the same. How the links work.
Price and free allowance
USD 0.002 per call, paid in USDC on Base, Polygon, Solana, BNB Chain or Arbitrum with x402. 3 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared by every image operation. MCP tool: image_crop at https://tanod.dev/mcp, where the free tier is automatic.
Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/images?via=image-crop-api as a custom connector (steps), then ask in plain words, for example "Crop this image to a square." The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.
Related guides: How to resize an image from a URL with an API, How to generate several thumbnail sizes from one image with an API, How to rotate or flip an image with an API. Back to tanod.dev or the guide index. Results are automated and heuristic.