Multiple options are separated with commas, e.g.
100x100,2x,fit,quality=low. Options can be in any order.
Full image size. No resizing takes place, e.g.
|Maximum image width and height, e.g. |
Dimensions are specified in CSS pixels, but without the
px suffix. Images are always resized preserving aspect ratio.
||Maximum image width. The height will vary depending on image's aspect ratio, e.g.
Exact interpretation of dimensions depends on the following options:
Multiply image dimensions by 2 or 3 for High-DPI ("Retina") displays. This is for use with HTML5's
srcset attribute that defines higher-resolution image alternatives.
By default resizing to
160x100 will create an image that is up to 160x100 pixels large, but:
160x100,2x will create an image that is up to 320x200 pixels large (in "device" pixels), and is optimized for display at size of 160x100 CSS
px on double-density displays.
Image is resized to completely fit within the given dimensions without cropping. Aspect ratio is preserved, so one of the dimensions may be smaller than the specified maximum. Small images will be enlarged if necessary.
500x500,fit would resize a 1000x200 image to 500x100, and a 16x16 image would be (wastefully) enlarged to 500x500.
fit, but the image is never enlarged. Image size is always equal or smaller than the given dimenions.
This is the default method, so you don't need to specify it explicitly:
is same as
500x500,scale-down would resize a 1000x200 image to 500x100, but a 16x16 image would stay 16x16.
Image is scaled and cropped to completely fill the given width and height, so that the resulting image always has exactly the dimensions specified, e.g.
First, the image is resized the same way as
fit, and then remaining space is padded with a background color (or transparent pixels in PNG). This produces images that always have the exact dimensions specified, but the content is never cropped. However, the extra pixels increase file size and waste browser's memory, so it should be used as last resort, when padding/centering in CSS is not possible (see
|RGB color as 3 or 6 hex digits, e.g. |
#), to use as a background color when adding padding to the image.
Specifies desired image quality when saving images in a lossy format. It's a trade-off: higher quality images cost more bandwidth and download slowly. Lower quality images are faster and take less disk space. ImageOptim works hard to give you the best of both.
⚠️ JPEG files can only have their quality decreased. If the input image is a low-quality JPEG, the output will not look any better. For best results, save original images as lossless PNG or JPEG at maximum quality, so that the ImageOptim API has the perfect source image to work with, and can produce images at optimum quality.
The quality presets are:
quality=low — offers smallest possible file size, but compression artefacts will be noticeable. Low quality setting is recommended for images that may be large, but are not critical for the site, e.g. backgrounds, splash screens.
quality=medium — balanced quality/filesize tradeoff giving small file sizes and barely noticeable lossy compression in normal viewing conditions. This is the default setting.
quality=high — avoids visible compression artefacts at the cost of higher (sometimes much higher) file size. This setting may be necessary for images that will be enlarged, sharpened or have contrast increased on the client-side (e.g. when used as a texture in a game).
quality=lossless — the optimization does not change a single pixel (this option is respected only if the image is not resized). Lossless-only optimization should be reserved only for special cases, e.g. images that are used as “originals” for print or further editing, such as logos in a press kit. It's not recommended for regular images displayed on a website, because lossless compression produces files many times larger than even the
high quality lossy setting.
By default the best file format is chosen automatically. You can request images converted to a specific format:
format=webm setting is for converting animated GIFs to VP9 WebM video.
Maximum time allowed to spend on optimization. In seconds, and decimal point is allowed. The default is 30 seconds.
This setting is for servers that can't wait too long for results, e.g. when calling the API from PHP which limits maximum execution time.
Good optimizations are slow, especially when images are large, so the longer the timeout the better. Be careful: if ImageOptim doesn't have enough time to finish optimization, it will return less optimized image, or even redirect to the source image as a fallback.