Image API
The Image API works via query string parameters.
In order to request images of the correct width, height or processed in other ways, you simply add the relevant parameters to the URL. For example, to stretch an image to fill a 200 x 200 pixel box, you would use a URL like this: https://yourdomain.libpx.com/my-images/avatar.jpg?width=200&height=200&mode=stretch.
Each parameter is described below. You can specify the parameters in any order.
Width
Specifies the width of the output image in pixels.
If this value is omitted or set to 0 (default) its value will be automatically calculated based on the supplied height value, so that the original image aspect ratio is preserved. If neither width nor height is defined, the original image size is used. And if both width and height are supplied, the image will be resized according to the mode setting.
While there is no maximum value for width, the output image will not exceed 6 megapixels (~2508x2508 if the image is a square). If the output image would exceed the limit, it will be scaled down automatically to the largest supported size.
Height
Specifies the height of the output image in pixels.
If this value is omitted or set to 0 (default) its value will be automatically calculated based on the supplied width value, so that the original image aspect ratio is preserved. If neither width nor height is defined, the original image size is used. And if both width and height are supplied, the image will be resized according to the mode setting.
While there is no maximum value for height, the output image will not exceed 6 megapixels (~2508x2508 if the image is a square). If the output image would exceed the limit, it will be scaled down automatically to the largest possible supported size.
Mode
Controls the resize mode when both a width and height are specified.
Available modes:
fit: Resize to fit within the boundaries defined by thewidthandheightparameters, while maintaining the original aspect ratio. If the output aspect ratio differs from the original, only one of the dimensions (width or height) will equal its set value, while the other will be smaller.crop: Resize to fill the entire area defined bywidthandheight, by maintaining the aspect ratio, but possibly clipping part of the image.stretch: Resize to fill the entire area defined bywidthandheight, by modifying the aspect ratio.
The default mode is fit.
Crop
Allows you to specify which part of the image is used.
To crop an image, you specify four parameters – the origin x and y (which defines the top left of the crop rectangle) and the dimensions w and h (which define the size of the rectangle).
Cropping is applied before other transformations. In particular, the crop values refer to the dimensions of the image before it has been resized. Note also that resizing may cause additional cropping of some part of the image if mode=crop is used.
The default mode is fit.
DPR
Specifies the device pixel ratio, between 0.1 and 10.0.
Acts as a multiplier for both the width and height. For example, using width=320&height=150&dpr=2 is equivalent to width=640&height=300.
This allows you to easily specify an image with the correct resolution for high dpi devices such as iPhones.
The default DPR is 1.0.
Blur
Blurs the image by a value relative to the image size, between 0 and 100.
The maximum blur radius (r) in pixels which corresponds to a blur value of 100 is calculated using the following formula for the image width (w) and height (h):
For a 640x480 pixel image, a blur value of 100 translates into a blur radius of 80 pixels.
This guarantees that the same blur value will result in the same level of blurriness for the same image at different sizes.
The default blur value is 0 (no blur).
Brightness
Adjusts the brightness of the image, with values between -100 and 100.
The default value is 0 (no brightness adjustment).
Contrast
Adjusts the contrast of the image, with values between -100 and 100.
The default value is 0 (no contrast adjustment).
Hue
Adjusts the hue of the image, with values between -100 and 100.
The default value is 0 (no hue adjustment).
Saturation
Adjusts the saturation of the image, with values between -100 and 100.
A saturation value of -100 turns the image into grayscale.
The default value is 0 (no saturation adjustment).
Gamma
Adjusts the gamma of the image, with values between -100 and 100.
The default value is 0 (no gamma adjustment).
Quality
Sets the quality of the output image, with values between 0 and 100.
This setting only affects JPEG images. Higher quality values result in images with a larger file size.
The default quality is 85.
Format
Normally images are processed and presented in the same format as the input image. This parameter allows you to force the output image to a particular format.
You can force images to be output as jpeg, png or webp, using format=jpeg, format=png or format=webp.
If the original image has an alpha channel (e.g. transparent PNGs), a white background will be applied if the output format does not support transparency.
Upscale
Defines whether the image can be resized past its original size. Set to false to prevent upscaling.
The default upscale value is true.
Debug
When LibPixel encounters an error processing an image it may still return a valid image. For example, when using a query string parameter value that's invalid, LibPixel may choose to use a default value or clamp it to the accepted range.
To see an error message instead (as an image), you can set the debug=true query string parameter.
Pass through parameters
If you wish to pass query string parameters to your server or image source, just prefix them with an underscore. LibPixel will strip the underscore and pass the parameter along when the image is fetched. For example:
https://yourdomain.libpx.com/my-images/avatar.jpg?width=200&_user=247
would cause LibPixel to fetch the image from the following URL:
https://my.image.source.com/images/avatar.jpg?user=247
(The image source in this case is https://my.image.source.com/images/)
Last updated
