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:
- 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 base64imageparameter. Passurland nothing else. If your image is local, host it first, or usePOST /v1/image/from-htmlwith the image inlined as a data URI. - Output comes back as base64 in the JSON
imagefield. 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 atx,ywithwidth×height. All four are required; missing any is a400.smartandsquare— both crop to the largest centred square that fits the image, and both ignorewidth/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=...°rees=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°rees=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=squareinstead ofresize+crop). format=jpegis lossy every time. If you're doing multi-step processing, requestpngfor intermediates and convert tojpegonly at the end.- Set
qualityexplicitly. Thecompressdefault is75; everywhere else it's85. 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/infofor a size baseline —compressonly reports post-compression bytes. maintain_aspect=truenever 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.
Related endpoints¶
- AI Image Processing (GPU) — background removal, upscaling, captioning, colourisation, face restoration
- Image Generation & Templates — pre-built template catalogue and Liquid rendering
- Extraction and Conversion — EXIF read, dimensions, dominant colours, format conversion