How to rotate or flip an image with an API

POST an image URL to /v1/image/rotate with an angle and/or a flip. It returns the rotated image as base64.

Request

angle is clockwise degrees (default 0). flip is none, horizontal, vertical or both. For angles that are not multiples of 90, expand (default true) grows the canvas and background fills the corners. 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/rotate \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://tanod.dev/icon.png", "angle": 90, "flip": "horizontal"}'

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/rotate \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://tanod.dev/icon.png", "angle": 90, "flip": "horizontal"}' \
  | jq -r '.data_base64' | base64 -d > rotated.png

Response

Response (example from the API spec, trimmed)

{
  "operation": "rotate",
  "input": {
    "format": "png",
    "width": 256,
    "height": 256,
    "bytes": 2183,
    "frames": 1,
    "animated": false,
    "has_alpha": true
  },
  "source_url": "https://tanod.dev/icon.png",
  "final_url": "https://tanod.dev/icon.png",
  "format": "png",
  "content_type": "image/png",
  "bytes": 2821,
  "width": 256,
  "height": 256,
  "data_base64": "iVBORw0KGgoAAAAN",
  "angle": 90.0,
  "flip": "horizontal",
  "notes": [],
  "source": {
    "library": "Pillow",
    "license": "MIT-CMU (HPND)",
    "url": "https://python-pillow.org"
  }
}

Limits and caveats

Lossless only at 90. Multiples of 90 degrees are lossless transposes. Other angles are resampled with bicubic interpolation, which softens edges slightly.

EXIF orientation first. With auto_orient (default true) the stored orientation is applied before your angle, so a rotated phone photo may already be upright.

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 rotator 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_rotate at https://tanod.dev/mcp, where the free tier is automatic.

All endpoints →

Related guides: How to crop an image to a box or an aspect ratio with an API, How to resize an image from a URL with an API, How to rotate the pages of a PDF with an API. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.