New API features and higher maximum allowed file size

Over the holiday season we’ve been working hard to deliver several highly-requested features to our users, both small and big, and all of which are quite useful – or so we hope :).

I’ll begin with the one which requires the least explanation.

Maximum allowed file size has increased

We have effectively doubled the maximum allowed file size for all formats, from 16MB to 32MB. We think that is more than reasonable. As always, we encourage API users who upload large files to make use of our callback_url API option, instead of letting your client wait for processing to complete. Why? So your application doesn’t have to hold the connection open for long.

New cropping options

Both of our “crop” and “fit” resize strategies can now make use of a new crop_mode parameter, which basically tells our API in which direction to apply the cropping.

To demonstrate what it does, I’ll use the below as the original or source image, of a guy gazing at the stars.

.

Using Kraken.io API’s crop strategy without specifying a crop_mode, the default behaviour is to crop from the center of the image, as shown below.

The above image has been cropped to dimensions of 250×250 pixels. Since the cropping area defaults to the center of the image, we get a resulting image of the guy’s head and shoulders, and lots of sky. But what if we want more of the guy without enlarging the box size of 250×250? Then we can add the crop_mode parameter to the request, and set a value of “b” (for bottom) or “s” (for South), and we get:

The JSON payload of the request I issued to get that result from the original was:

{
    "auth": {
        "api_key": "my_api_key",
        "api_secret": "my_api_secret"
    },
    "wait": true,
    "lossy": true,
    "resize": {
        "strategy": "crop",
        "crop_mode": "b",
        "width": 250,
        "height": 250
    }
}

As a cURL request:

curl -i http://api.kraken.io/v1/upload -X POST --form data='{"auth":{"api_key":"your_api_key", "api_secret":"your_api_secret"}, "wait":true, "lossy": true, "resize": { "strategy": "crop", "crop_mode": "b", "width": 250 , "height": 250 }}' --form upload=@krakenio-crop-mode-demo-resized.jpeg

crop_mode also works with our “fit” resize strategy. Our “fit” resize strategy works by fitting as much of the source image into the dimensions you provide as possible, trimming out the rest, and without messing up the aspect ratio. It is great for producing thumbnails from source images of wildly varying dimensions. For example, using the same source image, with the same parameters for width and height – and of course changing strategy to “fit”, we get the following result:

With the “fit” strategy, we can influence which part of the image will be trimmed away by adding crop_mode. In the following example I will set the crop_mode to “e” (for East), which has the same effect as setting it to “r” (for right):

The original image used in the above examples can be sourced from unsplash.
You can view the full documentation for image resizing at our image resizing documentation page, or go to more directly to our list of possible crop mode values.

Automatically orienting images

Some images possess an EXIF tag known as “Orientation”, which is intended to tell the image viewer/client how to correctly orient the image. For example, the below image has the orientation set to the value of 5 (to mean LeftTop). One way to directly obtain this value is to use ImageMagick’s identify command, as follows:

$ identify -verbose monalisa.jpg | grep Orientation
Orientation: LeftTop
exif:Orientation: 5

In fact, the below image has an EXIF Orientation of LeftTop, but WordPress doesn’t care! Grrrr.

If only there were a way to ensure that the image is oriented correctly regardless of which application is used as a viewing client.
Kraken.io provides such a feature. Add "auto_orient": true to your request and reap the benefits:

Request JSON:

{
    "auth": {
        "api_key": "my_api_key",
        "api_secret": "my_api_secret"
    },
    "wait": true,
    "lossy": true,
    "auto_orient": true
}

cURL:

curl http://api.kraken.io/v1/upload -X POST --form data='{"auth":{"api_key":"your_api_key", "api_secret":"your_api_secret"}, "wait": true, "lossy": true, "auto_orient": true}' --form upload=@monalisa.jpg

That’s much better.

Generating multiple sizes from a single input image

We have recently introduced a very highly-requested feature which we call Multi-Resizing. Multi-Resizing allows you to upload a single image to our API and instruct it on how to process that input image for up to ten “output” sizes. You can use multiple strategies, or a single strategy specifying different dimensions – whatever you like. To use Multi-Resize, instead of passing a single object as resize parameter, pass an array of object to the resize parameter.

Here is example request JSON for a Kraken.io Multi-Resize API call:

{
    "auth": {
        "api_key": "your_api_key",
        "api_secret": "your_api_secret"
    },
    "wait": true,
    "lossy": true,
    "resize": [{
        "id": "thumb",
        "strategy": "fit",
        "width": 100,
        "height": 100
    },
    {
        "id": "medium",
        "strategy": "auto",
        "width": 250,
        "height": 250
    },
    {
        "id": "large",
        "strategy": "auto",
        "width": 500,
        "height": 500
    }]
}

Note that the “id” property is required per resize object, and must be unique for each request.

Here’s the complete request example using cURL:

curl http://api.kraken.io/v1/upload \
-X POST \
--form data='{"auth":{"api_key":"your_api_key", "api_secret":"your_api_secret"}, "wait": true, "lossy": true, "resize": [{"id": "thumb", "strategy": "fit", "width": 100, "height": 100}, {"id": "medium", "strategy": "auto", "width": 250, "height": 250}, {"id": "large", "strategy": "auto", "width": 500, "height": 500}]}' \
--form upload=@krakenio-forest-multi-resize-original.jpeg

Here is the response JSON:

{
    "results": {
        "thumb": {
            "file_name": "krakenio-forest-multi-resize-original.jpeg",
            "original_size": 217128,
            "kraked_size": 6279,
            "saved_bytes": 210849,
            "kraked_url": "https://dl.kraken.io/api/59/4c/6c/90d6d782330f29f5c1c55cd85b/krakenio-forest-multi-resize-original.jpeg",
            "original_width": 800,
            "original_height": 600,
            "kraked_width": 100,
            "kraked_height": 100
        },
        "medium": {
            "file_name": "krakenio-forest-multi-resize-original.jpeg",
            "original_size": 217128,
            "kraked_size": 25066,
            "saved_bytes": 192062,
            "kraked_url": "https://dl.kraken.io/api/c7/89/fa/0c607cca3c849433ac0de5c96e/krakenio-forest-multi-resize-original.jpeg",
            "original_width": 800,
            "original_height": 600,
            "kraked_width": 250,
            "kraked_height": 188
        },
        "large": {
            "file_name": "krakenio-forest-multi-resize-original.jpeg",
            "original_size": 217128,
            "kraked_size": 86709,
            "saved_bytes": 130419,
            "kraked_url": "https://dl.kraken.io/api/8e/4a/45/a6ecadc3e5b0e57271af907dc0/krakenio-forest-multi-resize-original.jpeg",
            "original_width": 800,
            "original_height": 600,
            "kraked_width": 500,
            "kraked_height": 375
        }
    },
    "success": true
}

…and finally, here are the output images themselves:

Original

thumb

medium

large