| Param | Value | Default | ||
|---|---|---|---|---|
w | Output width in pixels (16–4000). | source width | ||
h | Output height in pixels (16–4000). | source height | ||
q | Output quality (20–100), or auto for content-aware. | 80 | ||
format (f) | auto, webp, avif, jpeg, png. | auto | ||
dpr | Device pixel ratio multiplier (1-4). w=400&dpr=2 returns 800 physical pixels. | 1 | ||
fit | cover, contain, fill, inside, outside. | cover | ||
gravity (g) | auto, smart, face, entropy, center, north, south, east, west, northeast, northwest, southeast, southwest. | auto | ||
fp | Manual focal point x,y in [0,1] or percentages. Centres the crop on this point. | — | ||
crop | Set to smart to run content-aware analysis instead of saliency. Equivalent to gravity=smart. | — | ||
trim (trimAlpha, trim-alpha) | Crop away fully transparent borders. Ideal for logos and PNG/WebP cutouts with alpha. Accepts 1, true, yes, or on. | false | ||
rotate (rot) | Rotate by degrees (-360 to 360). | 0 | ||
flip / flop | Vertical / horizontal mirror. Accepts 1, true, yes, or on. | false | ||
bg | Hex background for rotation/padding. Supports alpha. | transparent | ||
pad | Add equal padding around the image (0-1000). | 0 | ||
border | Add equal border around the image (0-400). | 0 | ||
borderColor | Hex border color. Supports alpha. | #000000 | ||
radius (r) | Rounded-corner radius in pixels. | 0 | ||
watermark (mark) | Stored image file ID to overlay as a watermark. Same workspace only. | — | ||
markW | Watermark width in pixels. Defaults to 18% of final image width. | auto | ||
markScale (mark-scale) | Scale watermark to a percentage of the base image width (0–100). Overrides default width when set. | auto | ||
markRot (mark-rot) | Rotate watermark counter-clockwise (0–359). | 0 | ||
markTile (mark-tile) | Tile the watermark across the image. Valid value: grid. | single mark | ||
markOpacity | Watermark opacity (0.05-1). | 0.78 | ||
markPosition | One of 7 anchor positions. | bottom-right | ||
markPad | Watermark margin from the image edge. | 24 | ||
text | Text overlay (URL-encoded, max 120 chars). | — | ||
textColor | Hex color for text. | #ffffff | ||
textSize | Font size in pixels (8–256). | 48 | ||
textPosition | One of 8 anchor positions. | bottom-center | ||
textFont | sans, serif, mono. | sans | ||
textBg | Optional hex background pill behind text. | none | ||
pixelate (px) | Pixelate the full image. 0 disables; 1-100 controls block size. | 0 | ||
blurFaces | Blur detected faces. Accepts 1, true, yes, or on. | false | ||
faceBlur | Blur strength for blurFaces (1-100). | 32 | ||
pixelateFaces | Pixelate detected faces instead of blurring them. Accepts 1, true, yes, or on. | false | ||
facePixelate | Pixel block size for pixelateFaces (2-100). | 16 | ||
blurRegion | Blur an explicit x,y,w,h output-pixel region. | — | ||
pixelateRegion | Pixelate an explicit x,y,w,h output-pixel region. | — | ||
plateRegion | Alias for blurring a license-plate x,y,w,h region. | — | ||
regions | Multiple regions: `blur:x,y,w,h:amount | pixelate:x,y,w,h:amount | plate:x,y,w,h`. | — |
preset | Reference a named preset. | — | ||
t / time | For video files in Convertly Storage: extract a poster frame at this timestamp in seconds, then apply image transforms. | 1 when poster params are used | ||
poster | Set to 1 to extract a poster frame from a stored video before applying image transforms. | — | ||
s | HMAC signature for gated content. | — |
Format negotiation
format=auto (the SDK default) tells the CDN to pick the best format per request based on the browser’s Accept header:
- AVIF for clients that advertise
image/avif - WebP for clients that advertise
image/webp - JPEG fallback for older browsers
Vary: Accept so the edge cache stays correct without poisoning — you’ll see at most two cache variants per URL (modern + JPEG) which is what you want.
To force a specific format, pass it explicitly: format=webp, format=avif, format=jpeg, or format=png.
Trim transparent borders
PNG, WebP, and other images with an alpha channel often ship with extra transparent padding around the subject — common for logos exported from design tools. Passtrim=1 to crop away fully transparent pixels before resize and encode:
trimAlpha=1, trim-alpha=1. Works in named presets too. Trim runs after EXIF auto-orient and before smart crop / resize, so the bounding box reflects the visible artwork.
Video poster frames
Stored video files in Convertly Storage can return an optimized image when you pass poster or image-format params. Convertly extracts a frame with FFmpeg, then runs the normal image transform pipeline (resize, format negotiation, smart crop, etc.).| Param | Purpose |
|---|---|
t or time | Timestamp in seconds for the frame to extract. |
poster=1 | Explicit poster mode (useful with presets). |
w, h, format, gravity, … | Same image params as raster sources. |
302).
Video delivery transforms
Use video output formats (mp4, webm, mov) to trim, resize, and transcode stored videos from the same CDN URL:
| Param | Purpose |
|---|---|
format / f / fm | Output container: mp4, webm, mov, or gif. |
so / start / ss | Clip start time in seconds. |
du / duration | Clip length in seconds (max 300). |
eo / end | Clip end time in seconds (alternative to duration). |
w, h | Scale output (maintains aspect ratio). |
q | Encode quality hint (20–100, maps to encoder CRF). |
mute=1 / an=1 | Strip audio track. |
fps | GIF frame rate (4–24, default 12). |
gif=1 | Same as format=gif. |
Content-aware quality
q=auto lets the CDN pick a quality based on what’s in the image. Photos compress well at lower quality without visible loss; flat graphics and screenshots need higher quality to avoid banding and ringing. Convertly analyzes the source on the first request and picks a quality from this band:
| Image type | Auto quality |
|---|---|
| Flat graphic / logo | 92 |
| Illustration / screenshot | 88 |
| Mixed content | 82 |
| Photo | 76 |
| Very high-detail photo | 72 |
q=auto works inside presets too. The analysis runs once per cache miss; once cached, subsequent requests serve the already-encoded bytes for free.
Smart cropping
When you set bothw and h with fit=cover (the default), Convertly crops the source to your aspect ratio. gravity, crop, or fp controls where the crop happens.
For focal-point workflows, entropy crops, and the /api/images/analyze endpoint, see Smart cropping & image analysis.
Pick a strategy
| Mode | What it does | Cost | When to use |
|---|---|---|---|
gravity=auto (default) | libvips attention strategy — saliency from saturation, skin tone, and edge density. | Cheapest. | Default; most portraits and product photography land correctly. |
gravity=smart / crop=smart | Runs the smartcrop algorithm: scores every candidate region for detail, saturation, and skin tone, then picks the highest aggregate score. | One extra ~50–100ms pass on the cache miss. | Hero images where the subject is off-centre, marketing imagery, anything where gravity=auto “almost” works. |
gravity=face | Real face detection (TinyFaceDetector model). Picks the highest-confidence face as the crop centre. If no face is detected, falls through to gravity=smart, then to saliency. | ~50–200 ms once per cache miss when a face is detected. | Portrait shots, team photos, marketing images that need to keep a person framed. |
gravity=entropy | Pure entropy-based pick (no saliency cues). | Cheapest. | Detail textures, dense product flat-lays, anything with no obvious subject. |
fp=x,y | Centre the crop on a hand-picked normalised coordinate. Overrides gravity when both w and h are set. | Cheapest — pure pixel math. | When you already know where the subject is (CMS-stored focal point, art-directed hero) or when you’ve called /api/images/analyze once and want to reuse the result. |
gravity=center / compass | Explicit corner / edge crop. | Cheapest. | When the source is composed and you don’t want any smart behaviour. |
fp=x,y is the most useful at scale: call /api/images/analyze once per upload, store the suggested focal point next to the file, then bake it into every <img> URL going forward. The CDN never re-runs analysis for those requests, so the only cost is the first analyse call. See Smart cropping → Combining focal points with the API for the full workflow.
Fit strategies
fit controls how the source is shaped into the requested w/h box:
fit | Behaviour |
|---|---|
cover (default) | Fills the box, cropping overflow. Pairs with gravity for smart cropping. |
contain | Fits inside the box, padding with transparency. |
fill | Stretches to fill the box. Distorts the image — only useful for solid-color or texture sources. |
inside | Scales down to fit the box without enlarging. |
outside | Scales to cover the box on the smallest axis. |
Canvas and presentation transforms
Use these when the CDN URL needs to produce finished UI assets, not just resized images:dpr multiplies the output pixels while preserving the intended layout size in your markup. For example, render an image into a 400px CSS slot with w=400&dpr=2; the CDN returns an 800px asset for high-density displays.
Watermarks must be image files stored in the same workspace as the delivery key. Convertly ignores missing or non-image watermark IDs instead of fetching arbitrary remote overlay URLs.
Text overlay
Render text directly into the image — useful for OG cards, social previews, dynamic badges. Addtext=… and the text composites on top of the resized image.
| Param | Value | Default |
|---|---|---|
text | URL-encoded text (max 120 chars). | — |
textColor | Hex color (#fff, #ffffff, or with alpha #ffffff80). | #ffffff |
textSize | Font size in pixels (8–256). | 48 |
textPosition | top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right. | bottom-center |
textFont | sans, serif, mono. | sans |
textBg | Optional hex background pill behind the text. | none |
og-card is a preset that sets the canvas (1200×630), font, and color — and only the text varies per page.
Pixelation and face privacy
Usepixelate when you want a deliberate pixel-art or obscured full-image effect:
blurFaces for privacy-safe previews, customer screenshots, testimonials, and UGC moderation flows:
Explicit region privacy
Use output-pixel coordinates when you already know what should be hidden:plateRegion is intentionally explicit in this release. Automatic license-plate detection needs a dedicated detection model and should be treated as a separate ML feature; coordinate-based plate privacy is reliable today and uses the same renderer path that automatic detection can call later.
Network-aware quality
If the visitor’s browser sendsSave-Data: on (data-saver mode on iOS / Android / Chrome / Opera), Convertly automatically drops the encode quality by 15 points (floored at 40) to halve bandwidth on slow networks. You don’t need to do anything — the route picks it up, sets Vary: Save-Data, and caches both variants independently.
How caching works
Every URL is deterministic. The endpoint sets long-lived immutable cache headers and varies onAccept and Save-Data:
Realistic cache ratios
The 95% number is achievable, not guaranteed. A few honest factors:- Edge caches are per-PoP, not global. A globally popular image may fetch from Convertly once per PoP until warm. For regional audiences this is usually invisible. Convertly also persists popular transform variants so repeat requests worldwide often skip re-encoding.
- LRU eviction. Edge caches evict less popular URLs under memory pressure. Long-tail content re-fetches more often than hot URLs.
- Cache-busting URLs. Anything like
?v=${Date.now()}collapses the cache ratio to ~0%. Keep URLs deterministic: same params → same URL → same cached bytes.
What counts as a delivery
A delivery is any request that reaches Convertly’s origin. These do not count:- Repeat hits served by Cloudflare, Vercel Edge, Fastly, or any other CDN.
- Browser cache hits.
- Service worker cache hits.