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/sdnflgqddm/Options/Image URL

sdnflgqddm

— username of your ImageOptim API account. Your API username is sdnflgqddm. We've updated all code examples to use it.

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/sdnflgqddm/100x100,crop/http://example.com/image.png For your 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/sdnflgqddm/full/http://example.com/kitten.jpg

widthxheight Maximum image width and height, e.g. https://img.gs/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/500x500,scale-down/http://example.com/kitten.jpg is same as https://img.gs/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/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/sdnflgqddm/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.

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:

location /imageoptim {
    # this if is required to preserve urlencoding of $1 and $2
    if ($request_uri ~ "/imageoptim/([^/]*)/(.*)") {
        proxy_pass https://img.gs/sdnflgqddm/$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.