Kraken.io Image Optimizer and Compressor for JPG, PNG, GIF

API Reference and Developer Documentation

Generating Multiple Sizes From a Single Input Image

Kraken.io API allows you to upload a single image and get back up to ten separate sizes, incorporating different resizing strategies, within a single response. Usefully, you can mix or match strategies - there is no restriction. Multi-resizing presents a number of advantages over the traditional one-request-per-size API.

Multi-resize allows you to generate entire responsive image sets based on a single image upload / image URL, avoiding the need to upload the same image over and over again for different sizes or strategies. Use multi-resize to minimize bandwidth usage and network overhead, and get the job done much faster.

To use our multi-resize feature, you will need to add an array of objects as value to the resize param. Each object must contain an unique id, together with a strategy, and the parameters specific to that strategy. The id can either be a string or a number, bearing in mind that numbers will get coerced to a string for the response. Here's an example multi-resize object requesting three different sizes:

{
    "auth": {
        "api_key": "your_api_key",
        "api_secret": "your_api_secret"
    },
    "wait": true,
    "lossy": true,
    "url": "https://example.com/image.png",
    "resize": [
        {
            "id": "small",
            "strategy": "fit",
            "width": 100,
            "height": 100
        },
        {
            "id": "medium",
            "strategy": "crop",
            "width": 300,
            "height": 300
        },
        {
            "id": "large",
            "strategy": "square",
            "size": 400
        }
    ]
}

<?php

require_once("Kraken.php");

$kraken = new Kraken("your_api_key", "your_api_secret");

$params = array(
    "url" => "https://example.com/image.png",
    "wait" => true,
    "lossy" => true,
    "resize" => array(
        array(
            "id" => "small",
            "strategy" => "fit",
            "width" => 100,
            "height" => 100
        ),
        array(
            "id" => "medium",
            "strategy" => "crop",
            "width" => 300,
            "height" => 300
        ),
        array(
            "id" => "large",
            "strategy" => "square",
            "size" => 400
        )
    )
);

$data = $kraken->url($params);

if ($data["success"]) {
    var_dump($data["results"]);
} else {
    echo "Fail. Error message: " . $data["message"];
}

var Kraken = require("kraken");

var kraken = new Kraken({
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
});

var params = {
    url: "https://example.com/image.png",
    wait: true,
    lossy: true,
    resize: [
        {
            id: "small",
            strategy: "fit",
            width: 100,
            height: 100
        },
        {
            id: "medium",
            strategy: "crop",
            width: 300,
            height: 300
        },
        {
            id: "large",
            strategy: "square",
            size: 400
        }
    ]
};

kraken.url(params, function (response) {
    if (response.success) {
        console.log(response.results);
    } else {
        console.log("Fail. Error message: %s", response.message);
    }
});

require 'rubygems'
require 'kraken-io'

kraken = Kraken::API.new(
    :api_key => 'your_api_key',
    :api_secret => 'your_api_secret'
)

params = {
    :wait => true,
    :lossy => true,
    :resize => [
        {
            'id' => 'small',
            'strategy' => 'fit',
            'width' => 100,
            'height' => 100
        },
        {
            'id' => 'medium',
            'strategy' => 'crop',
            'width' => 300,
            'height' => 300
        },
        {
            'id' => 'laege',
            'strategy' => 'square',
            'size' => 400
        }
    ]
}

data = kraken.url('https://example.com/image.png', params)

if data.success
    puts data['results']
else
    puts 'Fail. Error message: ' + data.message
end

package main

import (
    "log"
    "github.com/kraken-io/kraken-go"
)

func main() {
    kr, err := kraken.New("your_api_key", "your_api_secret")

    if err != nil {
        log.Fatal(err)
    }

    params := map[string]interface {} {
        "wait": true,
        "lossy": true,
        "url": "https://example.com/image.png",
        "resize": []interface {} {
            map[string]interface {} {
                "id": "small"
                "strategy": "fit",
                "width": 100,
                "height": 100
            },
            map[string]interface {} {
                "id": "medium",
                "strategy": "crop",
                "width": 300,
                "height": 300
            },
            map[string]interface {} {
                "id": "large",
                "strategy": "square",
                "size": 400
            }
        }
    }

    data, err := kr.URL(params)

    if err != nil {
        log.Fatal(err)
    }

    if data["success"] != true {
        log.Println("Failed, error message ", data["message"])
    } else {
        log.Println("Success, Optimized image URL: ", data["results"])
    }
}

from krakenio import Client

api = Client('your_api_key', 'your_api_secret')

data = {
    'wait': True,
    'resize': [
        {
            'id': 'small',
            'strategy': 'fit',
            'width': 100,
            'height': 100
        },
        {
            'id': 'medium',
            'strategy': 'crop',
            'width': 300,
            'height': 300
        },
        {
            'id': 'large',
            'strategy': 'square',
            'size': 400
        }
    ]
}

result = api.url('https://example.com/image.png', data);

if result.get('success'):
    print(result.get('results'))
else:
    print(result.get('message'))

Here is an example response from a multi-resize request. Note the id of each requested size, since that is how you will access each result:

{
    "results": {
        "small": {
            "file_name": "test.jpg",
            "original_size": 501361,
            "kraked_size": 123258,
            "saved_bytes": 378103,
            "kraked_url": "https://dl.kraken.io/api/c3/72/cf/3b13c3634cff28f1ad8ab849fc/header.png",
            "original_width": 576,
            "original_height": 576,
            "kraked_width": 100,
            "kraked_height": 100
        },
        "medium": {
            "file_name": "test.jpg",
            "original_size": 501361,
            "kraked_size": 14044,
            "saved_bytes": 487317,
            "kraked_url": "https://dl.kraken.io/api/7e/b5/a7/fa35d518dd82f02f405c0628da/header.png",
            "original_width": 576,
            "original_height": 576,
            "kraked_width": 300,
            "kraked_height": 300
        },
        "large": {
            "file_name": "test.jpg",
            "original_size": 501361,
            "kraked_size": 36776,
            "saved_bytes": 464585,
            "kraked_url": "https://dl.kraken.io/api/64/01/57/e9d09cd247976d8fe4d5afae42/header.png",
            "original_width": 576,
            "original_height": 576,
            "kraked_width": 400,
            "kraked_height": 400
        }
    },
    "success": true,
    "file_name": "header.png",
    "timestamp": 1450800885
}

As previously mentioned, you can supply up to ten objects per each multi-resize request. If you inadvertently include more than ten, Kraken.io will respond with the following:

HTTP/1.1 422 Unprocessable Entity

  {
      "success": false,
      "message": "You must limit the number of resize objects to a maximum of ten per request"
  }

Multi-Resize With External Storage

A multi-resize request can be used with one of the external file/object stores we support. However, you must specify a storage_path, per resize object:

{
    "auth": {
        "api_key": "your_api_key",
        "api_secret": "your_api_secret"
    },
    "wait": true,
    "lossy": true,
    "url": "https://example.com/image.png",
    "s3_store": {
        "key": "your_amazon_access_key",
        "secret": "your_amazon_secret_key",
        "bucket": "destination_bucket",
        "region": "your_s3_bucket_location"
    },
    "resize": [
        {
            "id": "small",
            "strategy": "fit",
            "width": 100,
            "height": 100,
            "storage_path": "images/layout/header-small.png"
        },
        {
            "id": "medium",
            "strategy": "crop",
            "width": 300,
            "height": 300,
            "storage_path": "images/layout/header-medium.png"
        },
        {
            "id": "large",
            "strategy": "square",
            "size": 400,
            "storage_path": "images/layout/header-large.png"
        }
    ]
}

<?php

require_once("Kraken.php");

$kraken = new Kraken("your_api_key", "your_api_secret");

$params = array(
    "url" => "https://example.com/image.png",
    "wait" => true,
    "lossy" => true,
    "s3_store" => array(
        "key" => "your_amazon_access_key",
        "secret" => "your-amazon-secret-key",
        "bucket" => "destination-bucket",
        "region" => "your-s3-bucket-location"
    ),
    "resize" => array(
        array(
            "id" => "small",
            "strategy" => "fit",
            "width" => 100,
            "height" => 100,
            "storage_path" => "images/layout/header-small.png"
        ),
        array(
            "id" => "medium",
            "strategy" => "crop",
            "width" => 300,
            "height" => 300,
            "storage_path" => "images/layout/header-medium.png"
        ),
        array(
            "id" => "large",
            "strategy" => "square",
            "size" => 400,
            "storage_path" => "images/layout/header-large.png"
        )
    )
);

$data = $kraken->url($params);

if ($data["success"]) {
    var_dump($data["results"]);
} else {
    echo "Fail. Error message: " . $data["message"];
}

var Kraken = require("kraken");

var kraken = new Kraken({
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
});

var params = {
    url: "https://example.com/image.png",
    wait: true,
    lossy: true,
    s3_store: {
        key: "your_amazon_access_key",
        secret: "your_amazon_secret_key",
        bucket: "destination_bucket",
        region: "your_s3_bucket_location"
    },
    resize: [
        {
            id: "small",
            strategy: "fit",
            width: 100,
            height: 100,
            storage_path: "images/layout/header-small.png"
        },
        {
            id: "medium",
            strategy: "crop",
            width: 300,
            height: 300,
            storage_path: "images/layout/header-medium.png"
        },
        {
            id: "large",
            strategy: "square",
            size: 400,
            storage_path: "images/layout/header-large.png"
        }
    ]
};

kraken.url(params, function (response) {
    if (response.success) {
        console.log(response.results);
    } else {
        console.log("Fail. Error message: %s", response.message);
    }
});

require 'rubygems'
require 'kraken-io'

kraken = Kraken::API.new(
    :api_key => 'your_api_key',
    :api_secret => 'your_api_secret'
)

params = {
    :wait => true,
    :lossy => true,
    :s3_store => {
        'key' => 'your_amazon_access_key',
        'secret' => 'your_amazon_secret_key',
        'bucket' => 'destination_bucket',
        'region' => 'your_s3_bucket_location'
    },
    :resize => [
        {
            'id' => 'small',
            'strategy' => 'fit',
            'width' => 100,
            'height' => 100,
            'storage_path' => 'images/layout/header-small.png'
        },
        {
            'id' => 'medium',
            'strategy' => 'crop',
            'width' => 300,
            'height' => 300,
            'storage_path' => 'images/layout/header-medium.png'
        },
        {
            'id' => 'laege',
            'strategy' => 'square',
            'size' => 400,
            'storage_path' => 'images/layout/header-large.png'
        }
    ]
}

data = kraken.url('https://example.com/image.png', params)

if data.success
    puts data['results']
else
    puts 'Fail. Error message: ' + data.message
end

package main

import (
    "log"
    "github.com/kraken-io/kraken-go"
)

func main() {
    kr, err := kraken.New("your_api_key", "your_api_secret")

    if err != nil {
        log.Fatal(err)
    }

    params := map[string]interface {} {
        "wait": true,
        "lossy": true,
        "url": "https://example.com/image.png",
        "s3_store" => map[string]interface {} {
            "key": "your_amazon_access_key",
            "secret": "your_amazon_secret_key",
            "bucket": "destination_bucket",
            "region": "your_s3_bucket_location"
        },
        "resize": []interface {} {
            map[string]interface {} {
                "id": "small"
                "strategy": "fit",
                "width": 100,
                "height": 100,
                "storage_path": "images/layout/header-small.png"
            },
            map[string]interface {} {
                "id": "medium",
                "strategy": "crop",
                "width": 300,
                "height": 300,
                "storage_path": "images/layout/header-medium.png"
            },
            map[string]interface {} {
                "id": "large",
                "strategy": "square",
                "size": 400,
                "storage_path": "images/layout/header-large.png"
            }
        }
    }

    data, err := kr.URL(params)

    if err != nil {
        log.Fatal(err)
    }

    if data["success"] != true {
        log.Println("Failed, error message ", data["message"])
    } else {
        log.Println("Success, Optimized image URL: ", data["results"])
    }
}

from krakenio import Client

api = Client('your_api_key', 'your_api_secret')

data = {
    'wait': True,
    's3_store': {
        'key': 'your_amazon_access_key',
        'secret': 'your_amazon_secret_key',
        'bucket": "destination_bucket",
        'region': 'your_s3_bucket_location'
    },
    'resize': [
        {
            'id': 'small',
            'strategy': 'fit',
            'width': 100,
            'height': 100,
            'storage_path': 'images/layout/header-small.png'
        },
        {
            'id': 'medium',
            'strategy': 'crop',
            'width': 300,
            'height': 300,
            'storage_path': 'images/layout/header-medium.png'
        },
        {
            'id': 'large',
            'strategy': 'square',
            'size': 400,
            'storage_path': 'images/layout/header-large.png'
        }
    ]
}

result = api.url('https://example.com/image.png', data);

if result.get('success'):
    print(result.get('kraked_url'))
else:
    print(result.get('message'))

It is worth noting that we strongly suggest setting the callback_url option in your multi-resize requests instead of "wait": true, since, depending on the input file size and number of images requested, the processing can take some time and letting Kraken.io call back to your system with the results provides more resiliency to HTTP timeouts. It also means that your client will not have to keep connections open for the duration of the processing.

Overriding Global Request Parameters Per Resize Object

By default, each resize object inherits certain values from the top level of the request - namely the values of the lossy, quality and sampling_scheme parameters. However, those values can be overridden per resize object. For example, when requesting JPEG outputs you can specify different quality values per each output.

Below are several examples of overriding global request properties within resize objects:

{
    "auth": {
        "api_key": "your_api_key",
        "api_secret": "your_api_secret"
    },
    "wait": true,
    "lossy": true,
    "url": "https://example.com/image.png",
    "resize": [
        {
            "id": "small",
            "strategy": "fit",
            "width": 100,
            "height": 100,
            "lossy": false
        },
        {
            "id": "medium",
            "strategy": "crop",
            "width": 300,
            "height": 300,
            "quality": 75
        },
        {
            "id": "large",
            "strategy": "square",
            "size": 400,
            "sampling_scheme": "4:4:4"
        }
    ]
}

<?php

require_once("Kraken.php");

$kraken = new Kraken("your_api_key", "your_api_secret");

$params = array(
    "url" => "https://example.com/image.png",
    "wait" => true,
    "lossy" => true,
    "resize" => array(
        array(
            "id" => "small",
            "strategy" => "fit",
            "width" => 100,
            "height" => 100,
            "lossy" => false
        ),
        array(
            "id" => "medium",
            "strategy" => "crop",
            "width" => 300,
            "height" => 300,
            "quality" => 75,
        ),
        array(
            "id" => "large",
            "strategy" => "square",
            "size" => 400,
            "sampling_scheme" => "4:4:4"
        )
    )
);

$data = $kraken->url($params);

if ($data["success"]) {
    var_dump($data["results"]);
} else {
    echo "Fail. Error message: " . $data["message"];
}

var Kraken = require("kraken");

var kraken = new Kraken({
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
});

var params = {
    url: "https://example.com/image.png",
    wait: true,
    lossy: true,
    resize: [{
        id: "small",
        strategy: "fit",
        width: 100,
        height: 100,
        lossy: false,
    },
    {
        id: "medium",
        strategy: "crop",
        width: 300,
        height: 300,
        quality: 75
    },
    {
        id: "large",
        strategy: "square",
        size: 400,
        quality: 60,
        sampling_scheme: "4:4:4"
    }]
};

kraken.url(params, function (response) {
    if (response.success) {
        console.log(response.results);
    } else {
        console.log("Fail. Error message: %s", response.message);
    }
});

require 'rubygems'
require 'kraken-io'

kraken = Kraken::API.new(
    :api_key => 'your_api_key',
    :api_secret => 'your_api_secret'
)

params = {
    :wait => true,
    :lossy => true,
    :resize => [{
        'id' => 'small',
        'strategy' => 'fit',
        'width' => 100,
        'height' => 100,
        'lossy' => false
    },
    {
        'id' => 'medium',
        'strategy' => 'crop',
        'width' => 300,
        'height' => 300,
        'quality' => 75
    },
    {
        'id' => 'large',
        'strategy' => 'square',
        'size' => 400,
        'sampling_scheme' => '4:4:4'
    }]
}

data = kraken.url('https://example.com/image.png', params)

if data.success
    puts data['results']
else
    puts 'Fail. Error message: ' + data.message
end

package main

import (
    "log"
    "github.com/kraken-io/kraken-go"
)

func main() {
    kr, err := kraken.New("your_api_key", "your_api_secret")

    if err != nil {
        log.Fatal(err)
    }

    params := map[string]interface {} {
        "wait": true,
        "lossy": true,
        "url": "https://example.com/image.png",
        "resize": []interface {} {
            map[string]interface {} {
                "id": "small"
                "strategy": "fit",
                "width": 100,
                "height": 100,
                "lossy": false
            },
            map[string]interface {} {
                "id": "medium",
                "strategy": "crop",
                "width": 300,
                "height": 300,
                "quality": 75
            },
            map[string]interface {} {
                "id": "large",
                "strategy": "square",
                "size": 400,
                "sampling_scheme": "4:4:4"
            }
        }
    }

    data, err := kr.URL(params)

    if err != nil {
        log.Fatal(err)
    }

    if data["success"] != true {
        log.Println("Failed, error message ", data["message"])
    } else {
        log.Println("Success, Optimized image URL: ", data["results"])
    }
}

from krakenio import Client

api = Client('your_api_key', 'your_api_secret')

data = {
    'wait': True,
    resize': [
        {
              'id': 'small',
              'strategy': 'fit',
              'width': 100,
              'height': 100,
              'lossy': False
          },
          {
              'id': 'medium',
              'strategy': 'crop',
              'width': 300,
              'height': 300,
              'quality': 75
          },
          {
              'id': 'large',
              'strategy': 'square',
              'size': 400,
              'sampling_scheme': '4:4:4'
          }
    ]
}

result = api.url('https://example.com/image.png', data);

if result.get('success'):
    print(result.get('kraked_url'))
else:
    print(result.get('results'))

Returning the optimized original-size image

Need to get back the optimized version of the original image in the same request without doing any resizing? Simply specify "strategy": "none" in one or more resize objects, and Kraken.io will optimize and compress that image, and give it back without altering its dimensions.

In this way, if we do not need to perform a second (or third) request if we need optimized versions of the original.

The following example demonstrates returning both a lossy and lossless version of the same image, in addition to one other size:

{
    "auth": {
        "api_key": "your_api_key",
        "api_secret": "your_api_secret"
    },
    "wait": true,
    "lossy": true,
    "url": "https://example.com/image.png",
    "resize": [
        {
            "id": "small",
            "strategy": "fit",
            "width": 100,
            "height": 100,
            "lossy": false
        },
        {
            "id": "medium",
            "strategy": "crop",
            "width": 300,
            "height": 300,
            "quality": 75
        },
        {
            "id": "large",
            "strategy": "square",
            "size": 400,
            "sampling_scheme": "4:4:4"
        }
    ]
}

<?php

require_once("Kraken.php");

$kraken = new Kraken("your_api_key", "your_api_secret");

$params = array(
    "url" => "https://example.com/image.png",
    "wait" => true,
    "lossy" => true,
    "resize" => array(
        array(
            "id" => "orig_size_lossless",
            "strategy" => "none",
            "lossy" => false
        ),
        array(
            "id" => "orig_size_lossy",
            "strategy" => "none"
        ),
        array(
            "id" => "large",
            "strategy" => "square",
            "size" => 400,
            "sampling_scheme" => "4:4:4"
        )
    )
);

$data = $kraken->url($params);

if ($data["success"]) {
    var_dump($data["results"]);
} else {
    echo "Fail. Error message: " . $data["message"];
}

var Kraken = require("kraken");

var kraken = new Kraken({
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
});

var params = {
    url: "https://example.com/image.png",
    wait: true,
    lossy: true,
    resize: [{
        id: "orig_size_lossless",
        strategy: "none",
        lossy: false
    },
    {
        id: "orig_size_lossy",
        strategy: "none"
    },
    {
        id: "large",
        strategy: "square",
        size: 400,
        quality: 60,
        sampling_scheme: "4:4:4"
    }]
};

kraken.url(params, function (response) {
    if (response.success) {
        console.log(response.results);
    } else {
        console.log("Fail. Error message: %s", response.message);
    }
});

require 'rubygems'
require 'kraken-io'

kraken = Kraken::API.new(
    :api_key => 'your_api_key',
    :api_secret => 'your_api_secret'
)

params = {
    :wait => true,
    :lossy => true,
    :resize => [{
        'id' => 'orig_size_lossless',
        'strategy' => 'none'
        'lossy' => false
    },
    {
        'id' => 'orig_size_lossy',
        'strategy' => 'crop'
    },
    {
        'id' => 'large',
        'strategy' => 'square',
        'size' => 400,
        'sampling_scheme' => '4:4:4'
    }]
}

data = kraken.url('https://example.com/image.png', params)

if data.success
    puts data['results']
else
    puts 'Fail. Error message: ' + data.message
end

package main

import (
    "log"
    "github.com/kraken-io/kraken-go"
)

func main() {
    kr, err := kraken.New("your_api_key", "your_api_secret")

    if err != nil {
        log.Fatal(err)
    }

    params := map[string]interface {} {
        "wait": true,
        "lossy": true,
        "url": "https://example.com/image.png",
        "resize": []interface {} {
            map[string]interface {} {
                "id": "orig_size_lossless"
                "strategy": "none",
                "lossy": false
            },
            map[string]interface {} {
                "id": "orig_size_lossy",
                "strategy": "none"
            },
            map[string]interface {} {
                "id": "large",
                "strategy": "square",
                "size": 400,
                "sampling_scheme": "4:4:4"
            }
        }
    }

    data, err := kr.URL(params)

    if err != nil {
        log.Fatal(err)
    }

    if data["success"] != true {
        log.Println("Failed, error message ", data["message"])
    } else {
        log.Println("Success, Optimized image URL: ", data["results"])
    }
}

from krakenio import Client

api = Client('your_api_key', 'your_api_secret')

data = {
    'wait': True,
    resize': [
        {
              'id': 'orig_size_lossless',
              'strategy': 'none',
              'width': 100,
              'height': 100,
              'lossy': False
          },
          {
              'id': 'orig_size_lossy',
              'strategy': 'none',
              'lossy': True
          },
          {
              'id': 'large',
              'strategy': 'square',
              'size': 400,
              'sampling_scheme': '4:4:4'
          }
    ]
}

result = api.url('https://example.com/image.png', data);

if result.get('success'):
    print(result.get('kraked_url'))
else:
    print(result.get('results'))