# 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](https://libpixel.com/docs/#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](https://libpixel.com/docs/#mode).
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](https://libpixel.com/docs/#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](https://libpixel.com/docs/#mode).
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](https://libpixel.com/docs/#width) and [height](https://libpixel.com/docs/#height) are specified.
Available modes:
* `fit`: Resize to fit within the boundaries defined by the `width` and `height` parameters, 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 by `width` and `height`, by maintaining the aspect ratio, but possibly clipping part of the image.
* `stretch`: Resize to fill the entire area defined by `width` and `height`, 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/`)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.libpixel.com/api-documentation/image-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
