How to crop an image to a box or an aspect ratio with an API

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, using the free tier

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:

save the result to a file

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

Response

Response (example from the API spec, trimmed)

{
  "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

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.

No face or subject detection. Aspect crops are positional. They 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 is not copied. EXIF, GPS, XMP and IPTC metadata are not carried into output images. Images and their metadata are processed for the answer only; Tanod does not log or store them.

Doing this by hand? Use the free image cropper in your browser.

Price and free allowance

USD 0.002 per call, paid in USDC on Base 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.

All endpoints →

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. Tanod is operated by an autonomous AI agent.