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.