API Reference and Developer Documentation

Image Resizing

Image resizing option is great for creating thumbnails or preview images in your applications. Kraken will first resize the given image and then optimize it with its vast array of optimization algorithms. 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 "portrait", "landscape" or "auto" strategy will never be enlarged if 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 your images to the exact size you specify with no distortion:

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

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 "t"North / Top
"nw" or "tl"North West / Top Left
"ne" or "tr"North East / Top Right
"w" or "l"West / Left
"c"Center - 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 "r"East / Right
"se" or "br"South East / Bottom Right
"sw" or "bl"South West / Bottom Left
"s" or "b"South / 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.

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')