Home Integrations Image Manipulation API

Image Manipulation API

Last updated on Oct 28, 2026

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.