Integration via GET URLs — ImageOptim API Documentation

Integration via URLs

You can serve resized images without storing them on your server. Prefix your images' URLs with ImageOptim API URL, and you'll get resized and optimized served from the new URL.

On this page:

The URL

https://img.gs/username/Options/Image URL

`username`	More about usernames
`Options`	— a comma-separated list of values and keywords that describe desired image dimensions, quality, etc. (width x height, 2x, full, scale-down, fit, crop, quality, timeout). This part of the URL is required. In case you don't want to specify any options, and only optimize images without resizing them, use the `full` option (as in full-size). List of options
`Image URL`	— an absolute URL of the image to optimize, e.g. `http://example.com/image.png`. For best results, please use JPEG files saved at very high quality (PNG files are good to). ImageOptim will automatically set optimum quality for optimized files if the source images had sufficiently high quality.

username

More about usernames

Options

— a comma-separated list of values and keywords that describe desired image dimensions, quality, etc. (width x height, 2x, full, scale-down, fit, crop, quality, timeout).

This part of the URL is required. In case you don't want to specify any options, and only optimize images without resizing them, use the full option (as in full-size).

List of options

Image URL

— an absolute URL of the image to optimize, e.g. http://example.com/image.png.

For best results, please use JPEG files saved at very high quality (PNG files are good to). ImageOptim will automatically set optimum quality for optimized files if the source images had sufficiently high quality.

https://img.gs/eX4mp1E4pI/100x100,crop/http://example.com/image.png For a site with this account ⤵︎ get the source image from example.com ⤴︎ and crop it to 100px square

Options overview

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`
`widthxheight`	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. Why CSS pixels are better than device pixels? It's convenient when dimensions in the markup, such as `<img width="…">` and `#img {width:…px}`, use the same unit as image dimensions in the API URLs, regardless of screen DPI. You don't have to multiply image dimensions for High-DPI (“Retina”) screens that require multiple “device pixels” per CSS pixel.
`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. Why specify `160x100,2x` instead of `320x200`? Knowing physical pixel size enables ImageOptim API to fine-tune image sharpness and perceptual lossy compression settings, which gives better quality and file size (when pixels are smaller, then image details are smaller too, and lossy compression can take advantage of that). Makes dimensions always match lengths specified in CSS and HTML Most of the time you need both 1x and 2x versions of each image (e.g. in `srcset`), and it's more convenient to append `,2x` to existing settings than to multiply the dimensions.
`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). Have you found an image that compresses worse than others? If you've found an image that doesn't look as good as you'd expect, please file a bug. We're trying to make all images look good enough at the default quality setting, so that you don't have to manually tweak the quality. `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. How is it better than quality scale 1-100? ImageOptim automatically chooses the exact compression quality for each image based on factors such as image size, format, and screen DPI. This gives better results than a single, fixed quality 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.

Caching

Because conversion and optimization is too expensive to perform from scratch on every request, images are always cached for at least 4 hours. To ensure that a new version of an image is available immediately, rename the image and refer to it in HTML/CSS under a new name, e.g. change hero.jpg to hero_v2.jpg.

Cookies are ignored. If you require login to view some images, you have two options: use the POST API that gives you 100% control of how images are served (and you can continue using your existing access controls), or give images very long, unique unguessable URLs (that's what Facebook does).

Maximum cache time is determined by the standard Cache-control and Expires headers sent by your server (see docs for nginx, Apache). The best practice is to make image files cacheable "forever" (e.g. set expiry to 1 year) and include version of the image in its URL.

Testing

An easy way verify whether you've modified your site's markup/templates is to right-click an image, choose Open Image in New Tab, and check if the address is "img.gs".

If you're proxying images via your server (as described below), then use curl -I followed by your image's URL. The output will contain Via: 1.1 imageoptim if it's been sent from the API.

Server configuration

Instead of embedding images directly from https://img.gs/… URLs you can use your own domain. This makes image URLs nicer and, if you use a CDN, allows your CDN to cache them.

To do this, you need to configure your web server to proxy the images.

nginx

In your server's vhost configuration, inside the server {…} block add:

Don't forget to register and replace the "eX4mp1E4pI" username in this code with your real username!

location /imageoptim {
    # this if is required to preserve urlencoding of $1 and $2
    if ($request_uri ~ "/imageoptim/([^/]*)/(.*)") {
        proxy_pass https://img.gs/eX4mp1E4pI/$1/http://$host/$2;
    }
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # these settings create faster keep-alive connection
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_request_buffering off;
    proxy_set_header Connection "";
}

With this change (after you restart the server) you'll be able to use ImageOptim API by prefixing image paths on your server with /imageoptim/options/. For example if you have:

<img src="/assets/hero.jpg">

you'll be able to use ImageOptim by changing the URL like this:

<img src="/imageoptim/300x200/assets/hero.jpg">

The example above will take assets/hero.jpg from your server, resize it to 300×200 pixels and serve the optimized version.

Instructions for other servers are coming soon. Alternatively, if you don't want to proxy images on-demand, but would rather store them permanently on your server, see the POST API documentation.

If you have any questions, feel free to e-mail.