Images API

Source Default Settings

Sources have specific attributes designed to control their default behavior when users try to render images through them.

Default Parameters

Default parameters are a list of query params that will be used by default when requests are generated for the source.

If we want for example to generate by default images in WebP format with a quality of 90 we can use the following default parameters:


Requests to a source with the previous default parameters will use these default values for format and quality parameters.

How to override default image params

Query parameters specified in the original URL will override the ones defined in the source default image params.

If you want to override the previous quality=90 default value you only need to specify a different value in the requested URL:


With the previous URL the image will be generated with a quality value of 75 instead of the default 90.

Common use cases

Some common use cases for default parameters include things like applying a general optimization to your entire images collection. This can be done for example with the following:


With the previous default parameters we are applying the following changes to our images:

  • interlace=true: generating progressive images so the loading experience of the images is improved for JPEG and PNG formats.
  • quantise=true: reducing the file size of PNG images generating a quantised version of them.
  • color-transform=srgb: transforming the color space of the image to a standard sRGB.
  • strip=all: reducing the final file size image removing all metadata, including ICC color profiles.

Another common use cases include applying a watermark to protect your images collection. This is something that we can do with the following default image params:


Notice that we are URL encoding watermark value from logo.svg?format=png to logo.svg%3Fformat%3Dpng. It is necessary to URL encode values to avoid problems with URL reserved characters. You should replace logo.svg with your watermark image.

With the previous default image params we are applying the following to our images:

Default Image

Default image allows sources to set a default image URL that will be served when the original request ends in an error (e.g a 4XX or 5XX HTTP error).

If a default image is set for a source and a request to the source ends in a 4XX or 5XX HTTP error, imglab will respond with a temporary redirect to the default image instead of returning the original error.

Any URL with a valid image can be used, even URLs to the same source.

To avoid redirect loops or ending with a default image that is not reachable confirm the following:

  • The default image URL is accessible and returns a valid image.
  • If the default image URL is using a imglab source with secured requests enabled you should confirm that the URL is including a valid signature parameter and working as expected.