Processing and Filters

Day-to-day image transformations: resize, crop, rotate, compress, remove backgrounds, apply filters, and adjust brightness/contrast/saturation.

How these endpoints take input

This is the part that trips people up, so read it before the examples.

Every endpoint on this page is GET, not POST, and takes its arguments as query-string parameters — not a JSON body.

# ✅ correct
curl "https://image.toolkitapi.io/v1/image/resize?url=https://example.com/photo.jpg&width=800" \
  -H "X-API-Key: YOUR_KEY"

# ❌ wrong — returns 405 Method Not Allowed
curl -X POST "https://image.toolkitapi.io/v1/image/resize" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "width": 800}'

Two consequences worth internalising:

  1. Source images must be publicly reachable URLs. Unlike the generation endpoints (/v1/image/from-html, /v1/image/from-template), these transformation endpoints do not accept a base64 image parameter. Pass url and nothing else. If your image is local, host it first, or use POST /v1/image/from-html with the image inlined as a data URI.
  2. Output comes back as base64 in the JSON image field. There is no URL in the response — you decode it yourself.
import base64

data = resp.json()
with open("out.jpg", "wb") as f:
    f.write(base64.b64decode(data["image"]))

All endpoints share a trailing format (png, jpeg, webp) and quality (1–100, default 85) parameter. url is capped at 2048 characters.

Endpoints

Transform

Endpoint Purpose
GET /v1/image/resize Resize to target dimensions
GET /v1/image/crop Crop by coordinates, smart center, or square
GET /v1/image/rotate Rotate by any angle
GET /v1/image/flip Flip horizontally or vertically
GET /v1/image/trim Auto-trim borders
GET /v1/image/pad Add padding or borders
GET /v1/image/composite Overlay one image onto another
GET /v1/image/dither Reduce to a limited colour palette

Optimize

Endpoint Purpose
GET /v1/image/compress Reduce image file size
GET /v1/image/strip-exif Remove metadata for privacy
GET /v1/image/remove-background Remove image backgrounds

Filters and adjustments

Endpoint Purpose
GET /v1/image/filter/grayscale Convert to grayscale
GET /v1/image/filter/blur Apply Gaussian blur
GET /v1/image/filter/sharpen Sharpen the image
GET /v1/image/filter/sepia Apply sepia tone
GET /v1/image/adjust/brightness Adjust brightness
GET /v1/image/adjust/contrast Adjust contrast
GET /v1/image/adjust/saturation Adjust saturation

Resize

GET /v1/image/resize?url=...

Parameter Type Default Notes
url string — Public image URL (required, ≤2048 chars)
width integer null Target width, 1–10000
height integer null Target height, 1–10000
maintain_aspect boolean true Lock aspect ratio when both dimensions are given
format enum png png, jpeg, webp
quality integer 85 1–100

You must supply at least one of width or height; omitting both is a 400.

You send maintain_aspect Result
width only either Other side scales proportionally
height only either Other side scales proportionally
both true (default) Fits inside the box — one side will be smaller than requested
both false Exact stretch to width×height, may distort
curl "https://image.toolkitapi.io/v1/image/resize?url=https://example.com/photo.jpg&width=800&maintain_aspect=true&format=jpeg&quality=85" \
  -H "X-API-Key: YOUR_KEY"
import base64
import requests

def resize(url: str, width: int, height: int | None = None) -> dict:
    params = {"url": url, "width": width, "format": "jpeg", "quality": 85}
    if height:
        params["height"] = height
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/resize",
        headers={"X-API-Key": "YOUR_KEY"},
        params=params,
        timeout=60,
    )
    r.raise_for_status()
    data = r.json()
    size = data["new_size"]
    return {"bytes": base64.b64decode(data["image"]), "w": size["width"], "h": size["height"]}

out = resize("https://example.com/photo.jpg", 800)
with open("resized.jpg", "wb") as f:
    f.write(out["bytes"])
print(f'{out["w"]}x{out["h"]}')
const params = new URLSearchParams({
  url: "https://example.com/photo.jpg",
  width: "800",
  maintain_aspect: "true",
  format: "jpeg",
});

const resp = await fetch(`https://image.toolkitapi.io/v1/image/resize?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
if (!resp.ok) throw new Error(`resize failed: ${resp.status}`);
const { image, original_size, new_size } = await resp.json();

await fs.promises.writeFile("resized.jpg", Buffer.from(image, "base64"));
console.log(`${original_size.width}x${original_size.height} → ${new_size.width}x${new_size.height}`);
Response
{
  "image": "iVBORw0KGgoAAAANSUhEUg...",
  "format": "jpeg",
  "original_size": { "width": 4000, "height": 3000 },
  "new_size": { "width": 800, "height": 600 }
}
Note the field names: `original_size` / `new_size` as nested objects, **not** flat `original_width` / `width` keys.

maintain_aspect: true uses Image.thumbnail(), which never upscales. Asking for width=5000 on a 400 px image returns a 400 px image. If you need enlargement, pass maintain_aspect=false with both dimensions.

Crop

GET /v1/image/crop?url=...

Parameter Type Default Notes
url string — Public image URL
mode enum smart coordinates, smart, square
x, y integer null Top-left offset (used with mode=coordinates)
width, height integer null Box size, 1–10000 (required for mode=coordinates)
  • coordinates — explicit box at x,y with width×height. All four are required; missing any is a 400.
  • smart and square — both crop to the largest centred square that fits the image, and both ignore width/height. They are currently identical implementations, so pick either.
# Centred square, perfect for avatars
curl "https://image.toolkitapi.io/v1/image/crop?url=https://example.com/photo.jpg&mode=square&format=png" \
  -H "X-API-Key: YOUR_KEY"

# Explicit box
curl "https://image.toolkitapi.io/v1/image/crop?url=https://example.com/photo.jpg&mode=coordinates&x=100&y=50&width=400&height=300" \
  -H "X-API-Key: YOUR_KEY"
import requests

def square_crop(url: str) -> bytes:
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/crop",
        headers={"X-API-Key": "YOUR_KEY"},
        params={"url": url, "mode": "square", "format": "png"},
        timeout=60,
    )
    r.raise_for_status()
    import base64
    return base64.b64decode(r.json()["image"])
const params = new URLSearchParams({
  url: "https://example.com/photo.jpg",
  mode: "coordinates",
  x: "100",
  y: "50",
  width: "400",
  height: "300",
});
const resp = await fetch(`https://image.toolkitapi.io/v1/image/crop?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image } = await resp.json();

A coordinates box extending past the image edge is clamped by PIL — you get a smaller image, not an error. Validate your coordinates against known dimensions if exact output size matters. To crop a non-square region, use mode=coordinates; there is no gravity/crop-to-aspect mode.

Rotate and flip

GET /v1/image/rotate?url=...&degrees=90 · GET /v1/image/flip?url=...&direction=horizontal

Endpoint Parameter Type Default Notes
rotate degrees float — Required. Clockwise positive
rotate expand boolean true Grow canvas so corners aren't clipped
rotate fill_color string #000000 Colour for exposed corners
flip direction enum horizontal horizontal, vertical

The rotation parameter is degrees (not angle) and it is required — omitting it returns 422.

curl "https://image.toolkitapi.io/v1/image/rotate?url=https://example.com/photo.jpg&degrees=90&expand=true" \
  -H "X-API-Key: YOUR_KEY"

curl "https://image.toolkitapi.io/v1/image/flip?url=https://example.com/photo.jpg&direction=vertical" \
  -H "X-API-Key: YOUR_KEY"
import requests

def rotate(url: str, degrees: float, expand: bool = True) -> dict:
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/rotate",
        headers={"X-API-Key": "YOUR_KEY"},
        params={"url": url, "degrees": degrees, "expand": expand, "format": "png"},
        timeout=60,
    )
    r.raise_for_status()
    return r.json()
const q = new URLSearchParams({ url: "https://example.com/photo.jpg", direction: "horizontal" });
const resp = await fetch(`https://image.toolkitapi.io/v1/image/flip?${q}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image, size } = await resp.json();

With expand=false and a non-multiple-of-90 rotation, corners are cropped away. Use expand=true (the default) unless you specifically want a fixed canvas. Positive degrees rotates clockwise.

Compress

GET /v1/image/compress?url=...

Parameter Type Default Notes
url string — Public image URL
quality integer 75 1 = smallest, 100 = best. Note: default differs from the 85 used elsewhere
format enum jpeg png, jpeg, webp
curl "https://image.toolkitapi.io/v1/image/compress?url=https://example.com/photo.jpg&quality=60&format=webp" \
  -H "X-API-Key: YOUR_KEY"
import base64
import requests

def compress(url: str, quality: int = 70) -> tuple[bytes, int]:
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/compress",
        headers={"X-API-Key": "YOUR_KEY"},
        params={"url": url, "quality": quality, "format": "webp"},
        timeout=60,
    )
    r.raise_for_status()
    data = r.json()
    return base64.b64decode(data["image"]), data["compressed_size_bytes"]
const q = new URLSearchParams({ url: "https://example.com/photo.jpg", quality: "60", format: "webp" });
const resp = await fetch(`https://image.toolkitapi.io/v1/image/compress?${q}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image, compressed_size_bytes, format } = await resp.json();
console.log(`${format}: ${compressed_size_bytes} bytes`);
Response
{
  "image": "UklGRiQAAABXRUJQVlA4...",
  "format": "webp",
  "quality": 60,
  "compressed_size_bytes": 48210
}
The response reports **only** the output size. There is no `original_size_bytes` / `size_bytes` pair — fetch `/v1/image/info` first if you need a before/after comparison.

Strip EXIF

GET /v1/image/strip-exif?url=...

Removes all metadata — GPS coordinates, camera serial numbers, timestamps, orientation tags. Run this on every user-uploaded image before publishing.

Parameter Type Default Notes
url string — Public image URL
format enum jpeg Also accepts gif, bmp, tiff here
quality integer 85 1–100
curl "https://image.toolkitapi.io/v1/image/strip-exif?url=https://example.com/photo.jpg&format=jpeg" \
  -H "X-API-Key: YOUR_KEY"
import base64
import requests

def strip_metadata(url: str) -> bytes:
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/strip-exif",
        headers={"X-API-Key": "YOUR_KEY"},
        params={"url": url, "format": "jpeg", "quality": 90},
        timeout=60,
    )
    r.raise_for_status()
    assert r.json()["exif_stripped"] is True
    return base64.b64decode(r.json()["image"])
const q = new URLSearchParams({ url: "https://example.com/photo.jpg", format: "jpeg" });
const resp = await fetch(`https://image.toolkitapi.io/v1/image/strip-exif?${q}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image, exif_stripped, size } = await resp.json();
console.log(exif_stripped, size.width, size.height);

Stripping EXIF also drops the ICC colour profile and orientation flag. Photos taken in portrait on a phone may appear sideways afterwards. Bake the rotation in with /v1/image/rotate first, or use an orientation-aware viewer.

Trim and pad

GET /v1/image/trim?url=... · GET /v1/image/pad?url=...

Endpoint Parameter Type Default Notes
trim tolerance integer 10 Colour tolerance for border detection, 0–255
pad top/right/bottom/left integer 0 Pixels per side, 0–2000
pad fill_color string #ffffff Hex fill colour
curl "https://image.toolkitapi.io/v1/image/trim?url=https://example.com/product.jpg&tolerance=10" \
  -H "X-API-Key: YOUR_KEY"

curl "https://image.toolkitapi.io/v1/image/pad?url=https://example.com/product.jpg&top=20&right=20&bottom=20&left=20&fill_color=%23f5f5f5" \
  -H "X-API-Key: YOUR_KEY"
import requests

# Trim white space, then pad to a consistent 40px white frame
def frame(url: str) -> dict:
    headers = {"X-API-Key": "YOUR_KEY"}

    trimmed = requests.get(
        "https://image.toolkitapi.io/v1/image/trim",
        headers=headers,
        params={"url": url, "tolerance": 12, "format": "png"},
        timeout=60,
    ).json()

    # pad takes a *url*, so re-host or skip straight to the decode step
    return trimmed
const q = new URLSearchParams({
  url: "https://example.com/product.jpg",
  top: "20", right: "20", bottom: "20", left: "20",
  fill_color: "#f5f5f5",
  format: "png",
});
const resp = await fetch(`https://image.toolkitapi.io/v1/image/pad?${q}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image } = await resp.json();

trim samples the pixel at (0,0) as the background colour. If your subject touches the top-left corner you'll get a no-op — check the trimmed boolean in the response. Remember to URL-encode the # in fill_color as %23.

Composite and dither

GET /v1/image/composite?url=... · GET /v1/image/dither?url=...

Endpoint Parameter Type Default Notes
composite base_url string — Base image (named base_url, not url)
composite overlay_url string — Image to layer on top (required)
composite mode enum normal normal, multiply, screen, overlay, add
composite x,y integer 0 Overlay offset
composite opacity float 1.0 0.0–1.0
dither colors integer 16 Palette size, 2–256
curl "https://image.toolkitapi.io/v1/image/composite?base_url=https://example.com/base.jpg&overlay_url=https://example.com/logo.png&mode=normal&x=20&y=20&opacity=0.8" \
  -H "X-API-Key: YOUR_KEY"

curl "https://image.toolkitapi.io/v1/image/dither?url=https://example.com/photo.jpg&colors=8&format=png" \
  -H "X-API-Key: YOUR_KEY"
import base64
import requests

def watermark(base: str, logo: str, x: int = 20, y: int = 20) -> bytes:
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/composite",
        headers={"X-API-Key": "YOUR_KEY"},
        params={
            "base_url": base,
            "overlay_url": logo,
            "mode": "normal",
            "x": x,
            "y": y,
            "opacity": 0.7,
            "format": "png",
        },
        timeout=60,
    )
    r.raise_for_status()
    return base64.b64decode(r.json()["image"])
const q = new URLSearchParams({
  base_url: "https://example.com/base.jpg",
  overlay_url: "https://example.com/logo.png",
  x: "20",
  y: "20",
  opacity: "0.8",
});
const resp = await fetch(`https://image.toolkitapi.io/v1/image/composite?${q}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image } = await resp.json();

If the overlay dimensions differ from the base, the overlay is resized to match the base before blending — it is never tiled or letterboxed. Both source images must be publicly reachable; composite takes two URLs (base_url + overlay_url). For AI quality background removal with alpha matting, see AI Image Processing (GPU); /v1/image/remove-background on this page is the fast CPU path.

Filters and adjustments

Endpoint Key parameter Range Default
GET /v1/image/filter/grayscale — — —
GET /v1/image/filter/blur radius 0.1–50.0 2.0
GET /v1/image/filter/sharpen — — Fixed unsharp mask (radius=2, percent=150)
GET /v1/image/filter/sepia — — —
GET /v1/image/adjust/brightness factor 0.0–5.0 required
GET /v1/image/adjust/contrast factor 0.0–5.0 required
GET /v1/image/adjust/saturation factor 0.0–5.0 required

The three adjust/* endpoints use factor, not value — and factor is required, so omitting it is a 422. 1.0 means "unchanged", 0.0 is fully flat/black, 5.0 is the maximum boost.

curl "https://image.toolkitapi.io/v1/image/filter/blur?url=https://example.com/photo.jpg&radius=5&format=png" \
  -H "X-API-Key: YOUR_KEY"

curl "https://image.toolkitapi.io/v1/image/adjust/brightness?url=https://example.com/photo.jpg&factor=1.2&format=jpeg" \
  -H "X-API-Key: YOUR_KEY"
import base64
import requests

def adjust(url: str, kind: str, factor: float) -> bytes:
    """kind: brightness | contrast | saturation"""
    assert kind in {"brightness", "contrast", "saturation"}
    r = requests.get(
        f"https://image.toolkitapi.io/v1/image/adjust/{kind}",
        headers={"X-API-Key": "YOUR_KEY"},
        params={"url": url, "factor": factor, "format": "jpeg"},
        timeout=60,
    )
    r.raise_for_status()
    return base64.b64decode(r.json()["image"])

open("brighter.jpg", "wb").write(adjust("https://example.com/photo.jpg", "brightness", 1.2))
const q = new URLSearchParams({ url: "https://example.com/photo.jpg", format: "png" });
const resp = await fetch(`https://image.toolkitapi.io/v1/image/filter/grayscale?${q}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { image, format } = await resp.json();

Error cases

Status Condition detail
400 resize called with neither width nor height Provide at least width or height
400 crop?mode=coordinates missing any of x/y/width/height x, y, width and height are required for coordinates mode
400 url unreachable, not an image, or SSRF-blocked Invalid image data: <reason>
400 Malformed fill_color on pad hex parse error
405 Any endpoint called with POST Method Not Allowed
422 Missing url; url over 2048 chars; out-of-range value (quality=0, radius=100) FastAPI validation error
401/403 Missing or invalid API key auth error
{ "detail": "Provide at least width or height" }

A 405 almost always means you copied a POST example from an older doc — switch to GET with query parameters.

Private IPs, localhost, and file:// URLs are rejected by the SSRF guard and surface as 400 Invalid image data. Image fetches are capped at 20 MB; larger files fail the same way.

Tips

  • Chain transformations server-side where you can. Each call decodes and re-encodes, so three separate calls means three rounds of JPEG generation loss. Compose as much as possible into one request (e.g. crop?mode=square instead of resize + crop).
  • format=jpeg is lossy every time. If you're doing multi-step processing, request png for intermediates and convert to jpeg only at the end.
  • Set quality explicitly. The compress default is 75; everywhere else it's 85. Relying on defaults gives inconsistent output across endpoints.
  • Strip EXIF before anything public. Phone photos routinely carry GPS coordinates. This is a privacy issue, not just a size optimisation.
  • Prefer /v1/image/info for a size baseline — compress only reports post-compression bytes.
  • maintain_aspect=true never upscales. For thumbnails that's exactly what you want; for enlargement it silently returns the original size.
  • URL-encode your query values. Signed URLs with ? and & inside them, or # in a hex colour, will break the request otherwise. Use a real URL builder as shown in the examples.
  • Don't parallelise blindly. These are CPU-bound and synchronous; a few concurrent calls are fine, twenty large images at once will queue.