Multiple options are separated with commas, e.g. 100x100,2x,fit,quality=low
. Options can be in any order.
full |
Full image size. No resizing takes place, e.g.
https://img.gs/eX4mp1E4pI/full/http://example.com/kitten.jpg
|
---|
widthx height
| Maximum image width and height, e.g. https://img.gs/eX4mp1E4pI/160x100/http://example.com/kitten.jpg
Dimensions are specified in CSS pixels, but without the px suffix. Images are always resized preserving aspect ratio.
|
---|
width
| Maximum image width. The height will vary depending on image's aspect ratio, e.g.
https://img.gs/eX4mp1E4pI/960/http://example.com/hero.jpg
Exact interpretation of dimensions depends on the following options:
|
---|
1x , 2x or 3x
default 1x
| 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.
https://img.gs/eX4mp1E4pI/160x100/http://example.com/regular.jpg
By default resizing to 160x100 will create an image that is up to 160x100 pixels large, but:
https://img.gs/eX4mp1E4pI/160x100,2x/http://example.com/retina.jpg
resizing to 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.
|
---|
fit |
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.
https://img.gs/eX4mp1E4pI/500x500,fit/http://example.com/kitten.jpg
500x500,fit would resize a 1000x200 image to 500x100, and a 16x16 image would be (wastefully) enlarged to 500x500.
|
---|
scale-down
the default |
Like 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:
https://img.gs/eX4mp1E4pI/500x500,scale-down/http://example.com/kitten.jpg
is same as
https://img.gs/eX4mp1E4pI/500x500/http://example.com/kitten.jpg
500x500,scale-down would resize a 1000x200 image to 500x100, but a 16x16 image would stay 16x16.
|
---|
crop |
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.
https://img.gs/eX4mp1E4pI/80x80,crop/http://example.com/avatar.jpg
|
---|
crop=auto |
Same as crop , but instead of cropping towards image center, automatically selects the most important aera of the image.
https://img.gs/eX4mp1E4pI/100x100,crop=auto/http://example.com/product.jpg
|
---|
crop=edge |
You can select which side of the image should be kept when cropping by adding an argument with one of top , left , right , bottom .
For example, this always keeps the top of the image, and the bottom will be cut off if necessary:
https://img.gs/eX4mp1E4pI/300x50,crop=top/http://example.com/sky.jpg
|
---|
crop=xxy |
You can select focal point for cropping. The image will be cropped so that the given point always remains in the image. The point's coordinates are specified within uncropped image, but the position is expressed using fractional numbers between 0 to 1 , e.g. 0 is top/left, 0.5 is center, 1 is bottom/right. These numbers are x pixel position divided by width and y pixel position divided by height. This way the focal point can be specified independently of image's actual size.
For example, crop focusing on a point that is in left third of the image, about 20% from the top of the image:
https://img.gs/eX4mp1E4pI/100x100,crop=0.333x0.2/http://example.com/portrait.jpg
|
---|
trim=border |
Removes solid-color border from the image. Only trims pixels that have exactly the same color, so it will remove borders added through image processing, but it's unlikely to remove edges of natual photos. Trimming is before any other resizing or cropping.
|
---|
bgcolor= RGB
default bgcolor=FFF
| RGB color as 3 or 6 hex digits, e.g. FFAAF8 (without # ), to use as a background color when adding padding to the image.
|
---|
quality= preset
default quality=medium
| 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.
|
---|
format= name
|
By default the best file format is chosen automatically. You can request images converted to a specific format: png , jpeg , webm or h264 .
The format=webm /format=h264 settings are for converting animated GIFs to video.
|
---|
timeout= seconds
default timeout=30
| 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.
|
---|