API Reference and Developer Documentation

Wait vs. Callback URL

For quick API reference and testing, you can find our OpenAPI docs page at the following link
https://api.kraken.io/v1/docs

Kraken.io gives you two options for fetching optimization and compression 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 and compression 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": "https://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" => "https://example.com/image.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: "https://example.com/image.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('https://example.com/image.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": "https://example.com/image.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 connection = Connection.Create("your_api_key", "your_api_secret");
var client = new Client(connection);
var response = client.OptimizeWait(
    new Uri("https://example.com/image.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('https://example.com/image.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 and compression has completed, Kraken.io, by default, will POST a message to the callback_url specified in your request as application/x-www-form-urlencoded data. If you would prefer to receive the response payload in the JSON format (application/json), which we strongly recommend, simply add "json": true to the request parameters. The ID in the received response will reflect the ID in the results posted to your Callback URL.

We recommend RequestBin as an easy way to capture optimization and compression results for initial testing.

Example Request:

{
    "auth": {
        "api_key": "your_api_key",
        "api_secret": "your_api_secret"
    },
    "url": "https://example.com/image.png",
    "callback_url": "https://awesome-website.com/kraken_results"
}

<?php

require_once("Kraken.php");

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

$params = array(
    "url" => "https://example.com/image.png",
    "callback_url" => "https://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: "https://example.com/image.png",
    callback_url: "https://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 => 'https://awesome-website.com/kraken_results'
}

data = kraken.url('https://example.com/image.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": "https://example.com/image.png",
        "callback_url": "https://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 connection = Connection.Create("your_api_key", "your_api_secret");
var client = new Client(connection);
var response = client.Optimize(
    new Uri("https://example.com/image.png"),
    new Uri("https://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': 'https://awesome-website.com/kraken_results'
}

result = api.url('https://example.com/image.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"
}