Image Manipulation API
The Image Manipulation API resizes, crops and watermarks the images stored in Estatebud, and delivers them through our
content delivery network (CDN). You change an image simply by adding options to its URL. There is nothing to install and
no API key needed.
Images are automatically delivered in the most efficient format each browser supports (AVIF, WebP or the original
JPEG/PNG), so you get smaller files and faster pages without changing your HTML.
Quick start
1. Take the image URL you received from Estatebud (from your website, the API or an XML feed):
https://estbd.io/1:a1b2c3d4/1834/6560c03ac1e5f.jpg
2. Choose your options as comma-separated name=value pairs:
w=600,h=400,f=crop
3. Insert the options as a new folder, directly before the file name:
https://estbd.io/1:a1b2c3d4/1834/w=600,h=400,f=crop/6560c03ac1e5f.jpg
That's it. This URL returns the image resized and cropped to 600 × 400 pixels.
URL format
https://<domain>/<image path>/<options>/<file name>
Part Example Notes Image path 1:a1b2c3d4/1834 Everything before the file name, exactly as you received it. Don't change
it. Options w=600,h=400,f=crop Comma-separated name=value pairs without spaces, or a single template name. File
name 6560c03ac1e5f.jpg Always last, so the URL ends with the file extension.
Rules for options
- Options can be written in any order, but use the same order everywhere. w=600,h=400 and h=400,w=600 produce the same
image, but are stored separately in the cache.
- Values containing /, ?, # or other special characters must be URL-encoded, for example with encodeURIComponent in
JavaScript or rawurlencode in PHP. Commas can't be used inside values.
- Every option needs a valid value (see the table below). An invalid value, for example w=abc or q=150, returns a 400
error instead of an image. Unknown options are ignored.
- The largest image you can request is 3840 × 2160 pixels (4K), counted after dpr. Larger sizes return a 400 error.
- A URL without options returns the full-size image, still in the best format for the browser.
Older URL format: URLs with the options after the file name (…/6560c03ac1e5f.jpg/w=600,h=400) still work and will keep
working, but they always return the original format (JPEG/PNG). Use the format above for anything new.
Options
Option Short Values Default width w whole pixels, up to 3840 after dpr original height h whole pixels, up to 2160 after
dpr original dpr number above 0, e.g. 1.5 or 2 1 fit f scale-down, crop, cover, contain scale-down quality q 1–100
depends on format format auto, original auto sharpen number, e.g. 0.5 off overlay_url ourl URL-encoded http(s) address
of an image none overlay_opacity oo 0–1 1 overlay_position op see Overlays below center overlay_top ot whole pixels
overlay_bottom ob whole pixels overlay_left ol whole pixels overlay_right or whole pixels overlay_rotate 90, 180, 270
overlay_repeat x, y
Width and height
The width (w) and height (h) options set the size of the image in pixels. How they are applied depends on the fit
option. If you only set one of them, the aspect ratio is preserved. The result can be at most 3840 pixels wide and 2160
pixels high.
dpr
Device pixel ratio. Multiplies width and height, so you can serve sharper images to high-resolution screens without
recalculating sizes. For example, w=400,dpr=2 returns an 800 pixel wide image. The multiplied size counts toward
the 3840 × 2160 maximum, so w=2000,dpr=2 (4000 pixels) is too large.
fit
Controls how the image is fitted to width and height. Images are never stretched, and cropping is always centred.
Mode Width and height set Only width or height set Enlarges small images? scale-down (default) Shrinks and crops to
exactly width × height. If the image is smaller than either value, it is returned at its original size. Shrinks
proportionally. No crop Shrinks and crops to exactly width × height. Values larger than the image are reduced to the
image's own size. Not allowed: set both (otherwise 400). No cover Resizes and crops to exactly width × height. Not
allowed: set both (otherwise 400). Yes contain Resizes proportionally until the image covers the whole area, without
cropping. One side matches, the other may be larger, up to 3840 × 2160. Resizes proportionally, up to 3840 × 2160. Yes
Example with a 1600 × 1200 photo:
Options scale-down crop cover contain w=800,h=300 800 × 300 800 × 300 800 × 300 800 × 600 w=2000,h=300 1600 × 1200 1600
× 300 2000 × 300 2000 × 1500 w=800 800 × 600 400 error 400 error 800 × 600
Tip: for thumbnails and listing cards that must have an exact size, use f=crop. It always fills the area and never
enlarges the image.
quality
Compression level from 1 (smallest file, lowest quality) to 100 (largest file, best quality). Most images look good
between 60 and 85.
If you don't set it, each format uses its own recommended default:
Format Default quality JPEG 90 WebP 80 AVIF 60
If you set q, the same value is used for every format. PNG images are always lossless, so quality doesn't apply to them.
format
Value Result auto (default) The best format the browser supports: AVIF, then WebP, then the original JPEG or PNG.
original Always the original format (JPEG or PNG).
With format=auto you don't need elements or separate URLs for each format: one URL serves every browser. Browsers and
apps that don't support AVIF or WebP automatically receive JPEG or PNG. Transparency in PNG images is kept in every
format.
Use format=original when:
- the image is meant to be downloaded. A browser that received AVIF or WebP saves the file in that format, even though
the URL ends with .jpg.
- the image is passed on to another system that only accepts JPEG or PNG, for example a property portal importing your
images.
format=auto only applies to URLs where the file name comes last, as described above. Older URLs with the options after
the file name always return the original format.
sharpen
Applies a sharpening filter. The value is the strength (radius) of the filter: start with 0.5 and increase if needed.
Sharpening is applied to the original image before resizing, so the effect is more subtle on small images.
Overlays and watermarks
Places an image, typically a logo or watermark, on top of the photo.
Option Description overlay_url / ourl Address of the overlay image, starting with http:// or https://. Use a PNG or SVG
with a transparent background. The address must be URL-encoded : ourl=https%3A%2F%2Fexample.com%2Flogo.png, not
ourl=https://example.com/logo.png. Unencoded, its slashes break the image URL and you get a 400 error. overlay_opacity /
oo Opacity from 0 (invisible) to 1 (as designed). overlay_position / op center, top, bottom, left, right, top-left,
top-right, bottom-left or bottom-right. Edge positions keep a 20 pixel margin. When this is set, the offset options
below are ignored. overlay_top / ot Distance in pixels from the top edge. Use either top or bottom: setting both returns
a 400 error. overlay_bottom / ob Distance in pixels from the bottom edge. overlay_left / ol Distance in pixels from the
left edge. Use either left or right: setting both returns a 400 error. overlay_right / or Distance in pixels from the
right edge. overlay_rotate Turns the overlay clockwise by 90, 180 or 270 degrees. It is placed by its turned size, so
positions work as expected. overlay_repeat x: a row of overlays across the full width of the image, at the overlay's
vertical position. y: a column of overlays down the full height, at the overlay's horizontal position. Combine with a
position, for example overlay_repeat=x,op=bottom for a row along the bottom.
Without any position options, the overlay is centred.
- Overlay size: the overlay scales with the image. It is shown at its own size on a 1920 pixel wide image, at half
size on a 960 pixel wide image, and so on. Design your overlay for a 1920 pixel wide photo.
- Updating an overlay: overlay images are cached. To change one, upload it under a new URL (or add a version such as
?v=2 before encoding it) instead of replacing the file.
- Account watermark: if your account has a default watermark, it is added automatically. Depending on your account
settings, it may be skipped on small images.
- If the overlay can't be loaded (its address doesn't respond, returns an error or isn't an image), the image is not
delivered without it: you get a 503 error, so a watermarked image is never shown unprotected. The overlay is tried
again after a minute.
Templates
Templates are ready-made sizes. Use the template name on its own, in place of the options:
https://estbd.io/1:a1b2c3d4/1834/medium/6560c03ac1e5f.jpg
Template Size Fit Notes thumb 398 × 224 cover No watermark small 796 × 448 scale-down medium 1138 × 640 scale-down
large 1536 × 864 scale-down hd1080 1920 × 1080 scale-down
Templates can't be combined with other options. If you need a variation, for example dpr=2, write the options out in
full instead: w=398,h=224,f=cover,dpr=2. The scale-down templates never enlarge an image: a photo smaller than the
template is returned at its own size. The thumb template always returns exactly 398 × 224.
Examples
Listing card, sharp on high-resolution screens
<img
src="https://estbd.io/1:a1b2c3d4/1834/w=400,h=300,f=crop/6560c03ac1e5f.jpg"
srcset="https://estbd.io/1:a1b2c3d4/1834/w=400,h=300,f=crop/6560c03ac1e5f.jpg 1x,
https://estbd.io/1:a1b2c3d4/1834/w=400,h=300,f=crop,dpr=2/6560c03ac1e5f.jpg 2x"
width="400" height="300" loading="lazy" alt="Living room">
Always put a descriptor (1x, 2x) after each URL in srcset. The URLs contain commas, and without descriptors the browser
can't tell where one URL ends and the next begins.
Full-width image that adapts to the screen
<img
src="https://estbd.io/1:a1b2c3d4/1834/w=1200/6560c03ac1e5f.jpg"
srcset="https://estbd.io/1:a1b2c3d4/1834/w=600/6560c03ac1e5f.jpg 600w,
https://estbd.io/1:a1b2c3d4/1834/w=1200/6560c03ac1e5f.jpg 1200w,
https://estbd.io/1:a1b2c3d4/1834/w=1920/6560c03ac1e5f.jpg 1920w"
sizes="100vw" alt="Front view">
Social sharing image (og:image)
<meta property="og:image" content="https://estbd.io/1:a1b2c3d4/1834/w=1200,h=630,f=crop,format=original/6560c03ac1e5f.jpg">
Download link for the full-size original
<a href="https://estbd.io/1:a1b2c3d4/1834/format=original/6560c03ac1e5f.jpg" download>Download photo</a>
Logo watermark in the bottom-right corner at 50% opacity
https://estbd.io/1:a1b2c3d4/1834/w=1200,ourl=https%3A%2F%2Fexample.com%2Flogo.png,oo=0.5,op=bottom-right/6560c03ac1e5f.jpg
A row of logos along the bottom
https://estbd.io/1:a1b2c3d4/1834/w=1200,ourl=https%3A%2F%2Fexample.com%2Flogo.png,oo=0.3,op=bottom,overlay_repeat=x/6560c03ac1e5f.jpg
Building URLs in code
These helpers URL-encode every value, so overlay addresses are always encoded correctly.
JavaScript
function imageUrl(url, options = {}) {
const params = Object.entries(options)
.map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
.join(',');
if (!params) return url;
const i = url.lastIndexOf('/');
return `${url.slice(0, i)}/${params}${url.slice(i)}`;
}
imageUrl('https://estbd.io/1:a1b2c3d4/1834/6560c03ac1e5f.jpg', { w: 600, h: 400, f: 'crop' });
// https://estbd.io/1:a1b2c3d4/1834/w=600,h=400,f=crop/6560c03ac1e5f.jpg
PHP
function imageUrl(string $url, array $options = []): string
{
if (!$options) {
return $url;
}
$params = [];
foreach ($options as $name => $value) {
$params[] = $name . '=' . rawurlencode((string) $value);
}
$i = strrpos($url, '/');
return substr($url, 0, $i) . '/' . implode(',', $params) . substr($url, $i);
}
echo imageUrl('https://estbd.io/1:a1b2c3d4/1834/6560c03ac1e5f.jpg', [
'w' => 1200,
'ourl' => 'https://example.com/logo.png',
'op' => 'bottom-right',
]);
// https://estbd.io/1:a1b2c3d4/1834/w=1200,ourl=https%3A%2F%2Fexample.com%2Flogo.png,op=bottom-right/6560c03ac1e5f.jpg
Errors
When an image can't be delivered, you get an error page with one of these status codes:
Status Meaning What to do 400 The URL has an invalid option: an unknown value (f=stretch), a value out of range (q=150),
a size above 3840 × 2160, crop or cover without both width and height, or an overlay address that isn't URL-encoded. Fix
the URL. The error doesn't go away by itself. 404 The image doesn't exist. Check the image path and file name. If the
image was only just uploaded, it shows up within a minute. 503 Temporarily unavailable, for example because the
watermark couldn't be loaded. Try again in a minute.
Good to know
- Supported images: options apply to JPEG and PNG images. Other files (GIF, SVG, PDF and so on) are delivered
unchanged.
- Metadata is removed: EXIF data, GPS location, camera details and colour profiles are stripped from every processed
image. Upload photos in the sRGB colour space for the most accurate colours.
- Caching: images are cached for up to 31 days by the CDN and up to a year by browsers. The first request for a new
size takes a little longer; after that it is served straight from the cache. Errors are only cached for a minute, so
a fixed URL or a newly uploaded image works almost straight away.
- Replacing an image: because images are cached for a long time, upload a changed photo under a new file name rather
than overwriting the old one. Estatebud does this automatically.