API Reference and Developer Documentation

Wait vs. Callback URL

Kraken gives you two options for fetching optimization results. With the wait option set the results will be returned in the response body. With the callback_url the results will be POSTed to the URL specified in your request.

We highly recommend use of the "callback_url" option over the "wait" option, as it eliminates the possibility of a request timeout occurring where large files are being Kraked.

Wait Option

With the wait option turned on for every request to the API, the connection will be held open until the image has been optimized. Once this is done you will get an immediate response with a JSON object containing your optimization results. To use this option simply set the "wait": true property in your request.

Example Request:

{
    "auth": {
        "api_key": "your-api-key",
        "api_secret": "your-api-secret"
    },
    "url": "http://awesome-website.com/images/header.jpg",
    "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
);

$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
};

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
}

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"
    }

    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", "your-api-secret");

var response = client.OptimizeWait(
    new Uri("http://awesome-website.com/images/header.png")
);

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
}

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

Example Response:

HTTP/1.1 200 OK

{
    "success": true,
    "file_name": "header.jpg",
    "original_size": 324520,
    "kraked_size": 165358,
    "saved_bytes": 159162,
    "kraked_url": "http://dl.kraken.io/d1/aa/cd/2a2280c2ffc7b4906a09f78f46/header.jpg"
}

Callback URL

With the Callback URL the HTTPS connection will be terminated immediately and a unique id will be returned in the response body. After the optimization is over Kraken will POST a message to the callback_url specified in your request in a JSON format application/json. The ID in the response will reflect the ID in the results posted to your Callback URL.

We recommend Hookbin as an easy way to capture optimization results for initial testing.

Example Request:

{
    "auth": {
        "api_key": "your-api-key",
        "api_secret": "your-api-secret"
    },
    "url": "http://awesome-website.com/images/header.png",
    "callback_url": "http://awesome-website.com/kraken_results"
}
<?php

require_once("Kraken.php");

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

$params = array(
    "url" => "http://awesome-website.com/images/header.png",
    "callback_url" => "http://awesome-website.com/kraken_results"
);

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

echo "Optimization ID: " . $data["id"];
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",
    callback_url: "http://awesome-website.com/kraken_results"
};

kraken.url(params, function (response) {
    console.log("Optimization ID: %s", response.id);
});
require 'rubygems'
require 'kraken-io'

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

params = {
    :callback_url => 'http://awesome-website.com/kraken_results'
}

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

puts 'Optimization ID: ' + data.id
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 {} {
        "url": "http://awesome-website.com/images/header.png",
        "callback_url": "http://awesome-website.com/kraken_results"
    }

    data, err := kr.URL(params)

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

    log.Println(data["id"])
}
using Kraken;
using Kraken.Http;

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

var response = client.Optimize(
    new Uri("http://awesome-website.com/images/header.png"),
    new Uri("http://awesome-website.com/kraken_results")
);

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

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

data = {
    'callback_url': 'http://awesome-website.com/kraken_results'
}

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

if result.get('id'):
    print result.get('id')
else:
    print result.get('message')

Example Response:

HTTP/1.1 200 OK

{
    "id": "18fede37617a787649c3f60b9f1f280d"
}

Results posted to the Callback URL:

HTTP/1.1 200 OK

{
    "id": "18fede37617a787649c3f60b9f1f280d"
    "success": true,
    "file_name": "header.jpg",
    "original_size": 324520,
    "kraked_size": 165358,
    "saved_bytes": 159162,
    "kraked_url": "http://dl.kraken.io/18/fe/de/37617a787649c3f60b9f1f280d/header.jpg"
}