Options overview

Multiple options are separated with commas, e.g. 100x100,2x,fit,quality=low. Options can be in any order.

Making the request

You should keep (cache) the optimized files. Use the API to process the images once (e.g. when they're uploaded) and then serve them from your server. This will give you best performance and maximum control over how files are handled.

With CURL

It's possible to use the API without any special libraries. curl is useful for trying things out.

curl -XPOST -O -L 'https://im2.io/eX4mp1E4pI/full/http://example.com/image.png'

• -XPOST makes a POST request rather than GET (that's a requirement of the API).
• -L enables following HTTP redirects, which are required by the API.
• -O saves output to a file. Without it curl would print tons of gibberish image data to your terminal. You can also use -o 'filename' to save image under a specific filename.

If you replace -O with -I you'll see HTTP headers instead — very useful for debugging!

Other useful flags you can add are --fail to handle errors in Bash, --silent to hide progress messages.

wget --method=POST 'https://im2.io/eX4mp1E4pI/full/http://example.com/image.png'

With PHP

We have a library for PHP. Or you can call the API with vanilla PHP:

<?php

// Full-size master image URL
$sourceImageUrl = 'http://example.com/image.png';

// Comma-separated options string
$options = 'full';

// Settings needed to switch to the POST method
$postContext = stream_context_create([
    'http' => [
        'method' => 'POST',
    ],
]);

// Get image data from the API
$imageData = file_get_contents(
    'https://im2.io/eX4mp1E4pI/' . $options . '/' . $sourceImageUrl,
    false, $postContext);

// At this point $imageData contains resized/optimized image
// You can save it to the disk on the server
file_put_contents('images/image-optimized.png', $imageData);

With NodeJS

You can use your favourite HTTP library (Node's built-in https module works too). We're using superagent module for the example:

npm install --save superagent

var superagent = require('superagent');
var fs = require('fs');

// Full-size master image URL
var sourceImageURL = 'http://example.com/image.png';

// Comma-separated options string
var options = 'full';

// Get image data from the API
superagent.post('https://im2.io/eX4mp1E4pI/' + options + '/' + sourceImageURL)
    .end(function(err, res) {
        var imageData = res.body;

        // At this point imageData contains resized/optimized image
        // You can save it to the disk on the server
        fs.writeFileSync('images/image-optimized.png', imageData);
    });

HTTP Response

Successes

If everything goes well, you'll either get a:

• response status 303 — a redirect to a URL to GET the optimized image from. Most HTTP libraries follow redirects automatically, so your code won't need to handle that explicitly.
• response status 200 — all OK, and the raw image file will be sent in the response body.

The image will be sent as binary data, with Content-Type: image/jpeg or image/png, etc. There's no extra ceremony, no JSON anywhere. Just the image file.

Warnings

In cases where options set were not quite right, but close enough to work, ImageOptim API will generate an optimized image as best as it can, but additionally it'll set a Warning HTTP header with a message detailing what was wrong. We recommend that you log any Warning headers found in responses and review them.

Failures

On error you'll get a response with status in 4xx or 5xx range, and a human-readable error description in the body.

You can open the URL you're requesting in a web browser to get specific information about the error.

• Response status 403 — if the username is missing or incorrect.
  • Sign up if you don't have one yet.
  • They're case-sensitive.
  • Watch out for superfluous slashes in the URL.
• Response status 400 — if the options or image URL are missing or incorrect.
  • The options part of the URL is required.
  • Options are comma-separated, without spaces.
  • If some options are wrong, the body of the response will contain more information.
• Response status 404 — we couldn't find the image you requested.
  • Is the image on public Internet? We can't fetch images from localhost. Use uploads instead.
  • Is the URL to the image absolute (with protocol and domain name)?
  • If you're including filenames in the URL that contain spaces or non-ASCII characters, you will need to URL-encode the filenames.
• Response status 402 — payment required.
  • You need to sign up for a paid plan.

Caching

ImageOptim API will respect cachability of images if fetches, and pass through equivalent Cache-Control headers.

Limits

Some of these limits can be increased — please contact support if you need higher limits.

Maximum image size is 10000x10000 pixels (100 megapixels). Maximum file size is 50MB. There's no hard limit on number of concurrent requests to the API (4-16 is reasonable).

Supported formats are JPEG, PNG and non-animated GIF. There is partial support for animated GIF and SVG.

Important

• Allow redirects! The API will use redirects to avoid timeouts and improve caching. Use curl -L in Bash. Other tools and libraries usually follow redirects by default.

• Set long request timeout. Good optimization takes time, especially if you're working with high-resolution images. We recommend at least 30-second timeout. If you're in a hurry and can't wait that long, add a timeout option to the request, and ImageOptim API will try to finish within the time given.

If you have problems with special characters, such as commas, colons or spaces in filenames, use URL-encoding.

If anything is wrong or missing, feel free to ask questions or leave feedback.