Transformations · API docs

How it works

Every upload and image response includes a url field: a direct CDN link. Append query parameters to transform what it serves.

URL

# The url, untouched
https://src.img.pro/4j2/abc12345.jpg

# WebP, 800px wide, a touch brighter
https://src.img.pro/4j2/abc12345.jpg?format=webp&w=800&brightness=1.1

One source can produce many cached variants with no per-transform charge. Each distinct URL is cached independently and parameter order doesn’t matter. Safeguards may ignore unsupported values or fall back to the source/default rendition.

Named sizes

The shortcut: ready-made variants you request with ?size=, no parameters to pick. The three responsive sizes appear in the response’s sizes object. social is requested the same way.

?size=s short side 320px: Thumbnails and avatars. Aspect ratio preserved.
?size=m short side 640px: Inline previews and feed cards. Aspect ratio preserved.
?size=l short side 1080px: Full-width hero and detail views. Aspect ratio preserved.
?size=social 1200×630: Fixed OpenGraph / social-card frame. Any source aspect is padded to fit.

URL

https://src.img.pro/4j2/abc12345.jpg?size=m

Format

Convert on the fly. format overrides the extension in the URL path, so …/abc.jpg?format=webp serves WebP even though the path says .jpg.

format jpg · png · webp · avif · gif: webp is the best quality-for-size balance (recommended); avif is the smallest; png is lossless with transparency; jpg is universal; gif is for legacy or animation. auto is intentionally unsupported: a cached transform is shared across clients, so it can’t depend on one client’s Accept header.

URL

https://src.img.pro/4j2/abc12345.jpg?format=webp

Resize & crop

Resize and crop with explicit dimensions. With the default scale-down fit, images are never enlarged: requesting a larger size is a no-op.

w 1–4096 px: Target width. Set w or h alone to scale proportionally; set both with fit to control how the image fills the box.
h 1–4096 px: Target height. Same rules as w.
fit default scale-down: How the image fills w×h: scale-down, contain, cover, crop, pad, squeeze. cover/crop fill and trim; contain/pad letterbox; scale-down never enlarges. An explicit cover/crop/pad will upscale to fill the box.
gravity default auto: Which part to keep when cropping: auto, face, left, right, top, bottom. face centers on detected faces.
zoom 0–1: Crop tightness around gravity=face. 0 = most context, 1 = tight.

URL

# 400×400 square crop centered on faces
https://src.img.pro/4j2/abc12345.jpg?w=400&h=400&fit=cover&gravity=face

Quality

Control output quality for lossy formats (JPEG / WebP / AVIF). Accepts a number or a named level.

q 1–100or high · medium-high · medium-low · low: Higher = better and larger; ~80 is a good web default. Named levels map to roughly 90 / 75 / 60 / 45. No effect on PNG: PNG output is always lossless truecolor, so use a lossy format for a smaller file.

URL

https://src.img.pro/4j2/abc12345.jpg?format=webp&q=80

Color & tone

Each is a decimal multiplier centered at 1 (no change). Omit a param to leave that channel untouched.

brightness 0–10 · default 1: 0 = black, 2 = twice as bright. Useful range ~0.5–2.
contrast 0–10 · default 1: 0 = flat mid-gray, >1 = punchier. Useful range ~0.7–2.
gamma 0–10 · default 1: <1 lightens midtones, >1 darkens them (0 and 1 are both no-ops). Useful range ~0.5–2.5. Direction is opposite to what some editors call “gamma”.
saturation 0–10 · default 1: 0 = grayscale, >1 = vivid. Useful range ~0.5–2.

All four are capped at 0–10, but values near the top produce visually useless extremes. Stay inside the “useful range” unless you’re after a specific effect.

URL

# Subtle warmth
https://src.img.pro/4j2/abc12345.jpg?brightness=1.1&contrast=1.05&saturation=1.1

# Black and white
https://src.img.pro/4j2/abc12345.jpg?saturation=0

Filters

Soften or sharpen detail without re-uploading.

blur 0–250 · default 0: Gaussian blur radius in pixels. 10–20 for a subtle wash, 40+ for a heavy placeholder. Useful for hero overlays and privacy masking.
sharp 0–10 · default 0: Unsharp-mask intensity. 1–3 subtle, 4–6 noticeable, 7+ aggressive (can ring on smooth areas).

URL

# Blurred hero background
https://src.img.pro/4j2/abc12345.jpg?blur=15

# Detail boost
https://src.img.pro/4j2/abc12345.jpg?sharp=4

Orientation

Rotate, mirror, or trim borders. Rotation at the supported angles involves no resampling; the output is re-encoded in the requested format like any transform (use PNG for a fully lossless result).

rotate 90 · 180 · 270: Clockwise rotation in degrees. Other values are ignored.
flip h · v · hv: Mirror horizontally, vertically, or both.
trim border: Auto-crop a uniform border color around the image (scanned documents, letterboxed screenshots).

URL

# Fix a sideways photo, then mirror it
https://src.img.pro/4j2/abc12345.jpg?rotate=90&flip=h

Privacy

Cameras, phones and editors embed GPS, device details, timestamps and edit history in image files. Public images carry pixels only: no public image carries location, camera or device details, capture time, edit history, embedded previews or provenance manifests. Their color is converted to sRGB, and an original’s rotation is applied to its pixels. Downloaded with download=1, an original keeps the name it was uploaded with, which may record when it was taken.

The original, at a URL with no valid transform parameter (download=1 is not one), is never served as uploaded: it is a high-quality copy re-encoded in the same format, lossless for PNG (an animated PNG becomes a still image), with the animation of a GIF or WebP kept, and every request gets the same copy. Its size is the copy’s, not the uploaded file’s. A HEIC upload is never served as a HEIC: its url ends in .jpg, a converted copy, and a .heic or .heif URL answers 404. The file you uploaded is stored unchanged.

Original files re-encoded without their embedded metadata

Changed October 1, 2026 (spec 4.7.0). An image’s original, at a URL with no valid transform parameter, is no longer served as uploaded: it is a high-quality copy re-encoded in the same format (lossless for PNG, though an animated PNG becomes a still image; animation kept for GIF and WebP), so its Content-Length is the copy’s, not the image’s bytes. Public images carry pixels only: no public image carries location, camera or device details, capture time, edit history, embedded previews or provenance manifests. Their color is converted to sRGB, and an original’s rotation is applied to its pixels. Downloaded with download=1, an original keeps the name it was uploaded with, which may record when it was taken. Each original’s ETag changes once, so a client downloads it once more. The file you uploaded is never changed. An original that cannot be decoded is not served (422). download=1 saves a transformed image, a converted format included, as {id}.{ext}; the original keeps the name it was uploaded with. From October 1, 2026, a signed-in member of the image’s team got the file as uploaded and a .heic or .heif URL answered 308; since spec 4.9.0 everyone gets this copy and such a URL answers 404.

Download

Add download=1 to any URL and the browser saves the file instead of showing it. The image is the same as without it.

download 1: Serve the image as an attachment. The original, at a URL with no valid transform parameter, is saved under the name it was uploaded with. A transformed image, a converted format included, is saved as {id}.{ext}: the image’s id and the extension of the format served.

URL

# The original, under the name it was uploaded with
https://src.img.pro/4j2/abc12345.jpg?download=1

# Saved as abc12345.webp
https://src.img.pro/4j2/abc12345.jpg?w=800&format=webp&download=1

Background

Remove the background with a single param (image segmentation runs on the edge) and optionally fill it with a solid color.

segment foreground: Replace the background with transparency. Add format=png so the alpha channel survives; otherwise the output follows the path extension and JPEG flattens transparency.
background: Fill color for transparent areas: a CSS named color (white, navy), hex (URL-encode # as %23, e.g. %23f5f5f5), or rgb(…) / rgba(…). After segment=foreground it swaps the background; on its own it fills any transparent pixels. Omit it and alpha-capable formats stay transparent, while others fill white.

URL

# Cutout on a white background (Amazon / Shopify ready)
https://src.img.pro/4j2/abc12345.jpg?segment=foreground&background=white&format=jpg

# Transparent PNG cutout
https://src.img.pro/4j2/abc12345.jpg?segment=foreground&format=png

Combining transforms

Chain parameters freely: order doesn’t matter, and the CDN runs everything in a single pass.

URL

# Privacy-blurred preview
https://src.img.pro/4j2/abc12345.jpg?blur=40

# Faded social card
https://src.img.pro/4j2/abc12345.jpg?format=jpg&contrast=0.9&saturation=0.8

# Rotated, sharpened, exported to AVIF
https://src.img.pro/4j2/abc12345.jpg?rotate=90&sharp=3&format=avif

Caching & formats

Caching: Each unique URL is cached independently at the edge. A cache miss generates the requested rendition; later matching requests reuse the cached result.
Upscaling: The default scale-down fit never enlarges beyond the source; cover / crop / pad upscale to fill the requested box.
Accepted uploads: JPEG, PNG, GIF, WebP, AVIF, and supported HEIC originals up to 20 MB (20,000,000 bytes). A file that can’t be decoded is refused and stores nothing.
Extensions: A URL ends in .jpg, .jpeg, .png, .gif, .webp or .avif, in any case: keep the one in the url the API returns, and use format to convert. Any other extension, .heic and .heif included, answers 404.
Limits: New transformations of an image may be limited for a while to prevent abuse: the URL then answers 429 with a short message. Named sizes, the original and versions already made always work. Write to support@img.pro if it gets in your way.
Retired parameters: fx, strength and tile were retired in spec 4.8.0. A URL that still carries them is served as the same URL without them.