API Reference and Developer Documentation

Image Resizing

Kraken.io Image Resizing API is great for creating thumbnails or preview images for your applications. Kraken.io will first resize the given image and then optimize it using our tried-and-tested optimization pipeline. The resize option needs a few parameters to be passed, such as the desired width and/or height, as well as a mandatory strategy property.

Images resized using the portrait, landscape or auto strategies will never be enlarged if the supplied width or height parameters are greater than the dimensions of the input image.
{
    "auth": {
        "api_key": "your-api-key",
        "api_secret": "your-api-secret"
    },
    "url": "http://awesome-website.com/images/header.png",
    "wait": true,
    "resize": {
        "width": 100,
        "height": 75,
        "strategy": "crop"
    }
}
<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "url" => "http://awesome-website.com/images/header.png",
    "wait" => true,
    "resize" => array(
        "width" => 100,
        "height" => 75,
        "strategy" => "crop"
    )
);

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

if ($data["success"]) {
    echo "Success. Optimized image URL: " . $data["kraked_url"];
} 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: "http://awesome-website.com/images/header.png",
    wait: true,
    resize: {
        width: 100,
        height: 75,
        strategy: "crop"
    }
};

kraken.url(params, function(status) {
    if (status.success) {
        console.log("Success. Optimized image URL: %s", status.kraked_url);
    } else {
        console.log("Fail. Error message: %s", status.message);
    }
});
require 'rubygems'
require 'kraken-io'

kraken = Kraken::API.new(
    :api_key => 'your-api-key',
    :api_secret => 'your-api-secret'
)

params = {
    :wait => true,
    :resize => {
        'width' => 100,
        'height' => 75,
        'strategy' => 'crop'
    }
}

data = kraken.url('http://awesome-website.com/images/header.png', params)

if data.success
    puts 'Success! Optimized image URL: ' + data.kraked_url
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,
        "url": "http://awesome-website.com/images/header.png",
        "resize": map[string]interface {} {
            "width": 100,
            "height": 75,
            "strategy": "crop"
        }
    }

    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["kraked_url"])
    }
}
using Kraken;
using Kraken.Http;

var client = Connection.Create("your-api-key", "you-api-secret");

var response = client.OptimizeWait(new Uri("http://awesome-website.com/images/header.png"),
    new OptimizeUploadWaitRequest() {
        ResizeImage = new ResizeImage {
            Width  = 100,
            Height = 75,
            Strategy = Strategy.crop
        }
    }
);

if (response.Result.StatusCode == HttpStatusCode.OK) {
    var url = response.Result.Body.KrakedUrl;
}
from krakenio import Client

api = Client('your-api-key', 'your-api-secret')

data = {
    'wait': True,
    'resize': {
        'width': 100,
        'height': 75,
        'strategy': 'crop'
    }
}

result = api.url('http://awesome-website.com/images/header.png', data);

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

Resizing Strategies

The strategy property can have one of the following values:

exact - Resize to exact width and height. Aspect ratio will not be maintained:

"resize": {
    "width": 100,
    "height": 75,
    "strategy": "exact"
}

portrait - Exact height will be set, width will be adjusted according to aspect ratio:

"resize": {
    "height": 75,
    "strategy": "portrait"
}

landscape - Exact width will be set, height will be adjusted according to aspect ratio:

"resize": {
    "width": 100,
    "strategy": "landscape"
}

auto - The best strategy (portrait or landscape) will be selected according to its aspect ratio:

"resize": {
    "width": 100,
    "height": 75,
    "strategy": "auto"
}

fit - This option will crop and resize your images to fit the desired width and height:

"resize": {
    "width": 100,
    "height": 75,
    "strategy": "fit"
}

crop - This option will crop an image to the exact size you specify. The resulting cropped image can optionally be scaled by inclusion of a scale, which accepts a number representing the percentage by which the image should be scaled:

"resize": {
    "width": 100,
    "height": 75,
    "strategy": "crop",
    "scale": 50
}

If you want to crop from a direction other than the default "center", you can specify a crop_mode parameter, which can take one of the following gravity (or direction) values:

n or tNorth / Top
nw or tlNorth West / Top Left
ne or trNorth East / Top Right
w or lWest / Left
cCenter - this is the default gravity or direction, and applied when the crop_mode parameter is left out, or an invalid value is passed.
e or rEast / Right
se or brSouth East / Bottom Right
sw or blSouth West / Bottom Left
s or bSouth / Bottom

For example, to crop the image from the South-West or bottom-left:

"resize": {
    "width": 100,
    "height": 75,
    "strategy": "crop",
    "crop_mode": "sw"
}
Please note that the crop_mode parameter can be used with both the fit and the crop strategies.

If you would like to crop a custom area from an image, you can do so by specifying the rectangular region you wish to extract as x, y, width and height. Optionally, you can pass a scale parameter (as mentioned above), which must be a number representing the percentage by which you would like to scale the image.

To illustrate, the following example will crop a 500x500 square from an image and then scale it down to produce a 250x250 square:

"resize": {
    "strategy": "crop",
    "x": 200,
    "y": 200,
    "width": 500,
    "height": 500,
    "scale": 50
}
The scale parameter also allows you to scale the crop to greater than 100% provided that the resulting dimension do not exceed 16384x16384 pixels.

square - This strategy will crop the image by its shorter dimension to make it a square, then resize it to the specified size:

"resize": {
    "size": 100,
    "strategy": "square"
}

fill - This strategy allows you to resize the image to fit the specified bounds while preserving the aspect ratio. The optional background property allows you to specify a color which will be used to fill the unused portions of the previously specified bounds.

The background property can be formatted in HEX notation #f60 or #ff6600, RGB rgb(255, 0, 0) or RGBA rgba(91, 126, 156, 0.7). The default background color is white. Example usage of fill strategy:

"resize": {
    "width": 100,
    "height": 75,
    "strategy": "fill",
    "background": "rgba(91, 126, 156, 0.7)"
}
If you would like to request several output sizes within a single request, incorporating one or more resizing strategies (and optionally other settings) please read our Generating Image Sets documentation.

Enhancing Resized Images

Most images resized using our API will yield results of excellent quality. However, in certain cases it might be a good idea to enhance the image by setting the "enhance": true flag in the resize object, when downsizing images to sizes much smaller than the original, say for very small thumbnails. The "enhance": true flag will apply various sharpening techniques to reduce ringing/haloing artifacts around the subject, as well as preserve more details on the subject itself.

"enhance": true is supported by all of the resizing strategies we offer.

High-contrast images which are composed of a stark subject against a flat background are good candidates for enhancement, particularly when you are converting them to a very small size. A good example would be product images taken on a white background, and resized to dimensions of less than 200x200.

To enable image enhancement for a resize request, simply set the "enhance": true flag within your resize object:

{
    "auth": {
        "api_key": "your-api-key",
        "api_secret": "your-api-secret"
    },
    "url": "http://awesome-website.com/images/header.jpg"
    "resize": {
        "width": 100,
        "height": 75,
        "strategy": "auto",
        "enhance": true
    }
    "wait": true
}
<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "url" => "http://awesome-website.com/images/header.png",
    "wait" => true,
    "resize" => array(
        "width" => 100,
        "height" => 75,
        "strategy" => "auto",
        "enhance" => true
    )
);

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

if ($data["success"]) {
    echo "Success. Optimized image URL: " . $data["kraked_url"];
} 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: "http://awesome-website.com/images/header.png",
    wait: true,
    resize: {
        width: 100,
        height: 75,
        strategy: "auto",
        enhance: true
    }
};

kraken.url(params, function(status) {
    if (status.success) {
        console.log("Success. Optimized image URL: %s", status.kraked_url);
    } else {
        console.log("Fail. Error message: %s", status.message);
    }
});
require 'rubygems'
require 'kraken-io'

kraken = Kraken::API.new(
    :api_key => 'your-api-key',
    :api_secret => 'your-api-secret'
)

params = {
    :wait => true,
    :resize => {
        'width' => 100,
        'height' => 75,
        'strategy' => 'auto',
        'enhance' => true
    }
}

data = kraken.url('http://awesome-website.com/images/header.png', params)

if data.success
    puts 'Success! Optimized image URL: ' + data.kraked_url
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,
        "url": "http://awesome-website.com/images/header.png",
        "resize": map[string]interface {} {
            "width": 100,
            "height": 75,
            "strategy": "auto",
            "enhance": true
        }
    }

    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["kraked_url"])
    }
}
using Kraken;
using Kraken.Http;

var client = Connection.Create("your-api-key", "you-api-secret");

var response = client.OptimizeWait(new Uri("http://awesome-website.com/images/header.png"),
    new OptimizeUploadWaitRequest() {
        ResizeImage = new ResizeImage {
            Width  = 100,
            Height = 75,
            Strategy = Strategy.auto,
            Enhance = true
        }
    }
);

if (response.Result.StatusCode == HttpStatusCode.OK) {
    var url = response.Result.Body.KrakedUrl;
}
from krakenio import Client

api = Client('your-api-key', 'your-api-secret')

data = {
    'wait': True,
    'resize': {
        'width': 100,
        'height': 75,
        'strategy': 'auto',
        'enhance': True
    }
}

result = api.url('http://awesome-website.com/images/header.png', data);

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