NAV
api
cURL Python

Introduction

The Imagga API is a set of image understanding and analysis technologies available as a web service that allows you to automate the process of analyzing, organizing and searching through large collections of unstructured images.

The services are hosted at our end and are available on a software-as-a-service (SaaS) basis which makes them very flexible, scalable (applicable to any size of image collection), and affordable. All you have to do to begin using them is to Sign Up and you can immediately start sending requests to our REST API.

Let's get started.

Getting Started

It's as simple as 1, 2, 3 to get started building with Imagga API.

1. Sign Up

First thing you should do in order to begin using Imagga API is go to our website, choose a subscription plan that fits your needs or go with the free one and sign up.

Upon a successful sign up, you will be presented with your profile dashboard page where the api credentials could be found:

In the same section you can see the complete value of the basic authorization header already prepared for you so you can just copy and and paste it without doing the base64 encoding yourself. A code snippet to get you started is also available, again ready to be tried.

2. Send a request

With just a simple GET request to the auto-tagging endpoint (/tagging) you receive numerous keywords describing the given photo. Here's what our request should look like:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/tagging?url=http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg
import requests

api_key = ''
api_secret = ''
image_url = 'http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg'

response = requests.get('https://api.imagga.com/v1/tagging?url=%s' % image_url,
                auth=(api_key, api_secret))

print response.json()
<?php

$image_url = 'http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg';
$api_credentials = array(
'key' => '',
'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/tagging?url='.$image_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String imageUrl = "http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg",
apiKey = "",
apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/tagging")
    .queryString("url", imageUrl)
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_url = 'http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get "https://api.imagga.com/v1/tagging?url=#{image_url}", { :Authorization => auth }
puts response
var request = require('request'),
apiKey = '',
apiSecret = '',
imageUrl = 'http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg';

request.get('https://api.imagga.com/v1/tagging?url='+encodeURIComponent(imageUrl), function (error, response, body) {
console.log('Status:', response.statusCode);
console.log('Headers:', JSON.stringify(response.headers));
console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
[request setUrl:@"https://api.imagga.com/v1/tagging?url=http%3A%2F%2Fdocs.imagga.com%2Fstatic%2Fimages%2Fdocs%2Fsample%2Fjapan-605234_1280.jpg"];
[request setHeaders:headers];
[request setUsername:@"your-api-key"];
[request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
NSInteger code = response.code;
NSDictionary *responseHeaders = response.headers;
UNIJsonNode *body = response.body;
NSData *rawBody = response.rawBody;
}];
package main

import (
"fmt"
"io/ioutil"
"net/http"
)

func main() {
client := &http.Client{}
api_key := ""
api_secret := ""
image_url := "http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg"

req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/tagging?url="+image_url, nil)
req.SetBasicAuth(api_key, api_secret)

resp, err := client.Do(req)

if err != nil {
fmt.Println("Error when sending request to the server")
return
}

defer resp.Body.Close()
resp_body, _ := ioutil.ReadAll(resp.Body)

fmt.Println(resp.Status)
fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";
            string imageUrl = "http://docs.imagga.com/static/images/docs/sample/japan-605234_1280.jpg";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Accept.Clear ();
                client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

                HttpResponseMessage response = await client.GetAsync (String.Format("tagging?url={0}", imageUrl));

                HttpContent content = response.Content;
                string result = await content.ReadAsStringAsync ();
                Console.WriteLine (result);
            }
        }
    }
}
And if the request was successful we will find a list of tags with confidence levels in the response. The confidences are represented by a percentage number from 0 to 100 where 100 means that the API is absolutely sure the tags must be relevant anf confidence < 30 means that there is a higher chance that the tag might not be relevant. Read best practices on filtering the tags by their confidence levels.
{
    "results": [
    {
        "tagging_id": null,
        "image": "http://playground.imagga.com/static/img/example_photos/japan-605234_1280.jpg",
        "tags": [
            {
                "confidence": 63.34683699627821,
                "tag": "valley"
            },
            {
                "confidence": 60.663772505979225,
                "tag": "mountain"
            },
            {
                "confidence": 44.391272821638736,
                "tag": "canyon"
            },
            {
                "confidence": 42.08315110172071,
                "tag": "landscape"
            },
            {
                "confidence": 33.52198895357515,
                "tag": "geological formation"
            },
            {
                "confidence": 32.70286655036308,
                "tag": "mountains"
            },
            {
                "confidence": 28.626239974019278,
                "tag": "glacier"
            },
            {
                "confidence": 28.36,
                "tag": "natural depression"
            },
            {
                "confidence": 28.03482547523986,
                "tag": "ravine"
            },
            {
                "confidence": 27.270388918558336,
                "tag": "sky"
            },
            {
                "confidence": 26.131397502662388,
                "tag": "rock"
            },
            {
                "confidence": 23.119592918013478,
                "tag": "travel"
            },
            {
                "confidence": 21.751862779399755,
                "tag": "alp"
            },
            {
                "confidence": 20.957200508107682,
                "tag": "national"
            },
            {
                "confidence": 20.154218745527803,
                "tag": "park"
            },
            {
                "confidence": 19.826853236611736,
                "tag": "stone"
            },
            {
                "confidence": 19.71797256086285,
                "tag": "water"
            },
            {
                "confidence": 18.049516159959957,
                "tag": "river"
            },
            {
                "confidence": 17.81677847426883,
                "tag": "hill"
            },
            {
                "confidence": 17.306344860667394,
                "tag": "tourism"
            },
            {
                "confidence": 17.1930946873609,
                "tag": "clouds"
            },
            {
                "confidence": 16.53629074937248,
                "tag": "scenic"
            },
            {
                "confidence": 15.99005210034468,
                "tag": "peak"
            },
            {
                "confidence": 15.79301277042808,
                "tag": "lake"
            },
            {
                "confidence": 15.533213250797763,
                "tag": "scenery"
            },
            {
                "confidence": 15.454099536554168,
                "tag": "snow"
            },
            {
                "confidence": 15.233014058156586,
                "tag": "outdoors"
            },
            {
                "confidence": 15.212382108222897,
                "tag": "range"
            },
            {
                "confidence": 15.042643317948368,
                "tag": "hiking"
            },
            {
                "confidence": 14.9591591901237,
                "tag": "tree"
            },
            {
                "confidence": 14.788738496684614,
                "tag": "forest"
            },
            {
                "confidence": 12.853831449887238,
                "tag": "grass"
            },
            {
                "confidence": 12.24290824762163,
                "tag": "desert"
            },
            {
                "confidence": 12.095999999999998,
                "tag": "natural elevation"
            },
            {
                "confidence": 12.039312862163559,
                "tag": "america"
            },
            {
                "confidence": 11.494168108100943,
                "tag": "environment"
            },
            {
                "confidence": 11.250836858545538,
                "tag": "usa"
            },
            {
                "confidence": 10.936236202034552,
                "tag": "panorama"
            },
            {
                "confidence": 10.839160709179025,
                "tag": "trees"
            },
            {
                "confidence": 10.771086204657593,
                "tag": "south"
            },
            {
                "confidence": 10.38547316071002,
                "tag": "summer"
            },
            {
                "confidence": 9.968137982581291,
                "tag": "cloud"
            },
            {
                "confidence": 9.961056039241079,
                "tag": "wild"
            },
            {
                "confidence": 9.840531136910435,
                "tag": "natural"
            },
            {
                "confidence": 9.647633204287587,
                "tag": "geology"
            },
            {
                "confidence": 9.623289555517639,
                "tag": "rocky"
            },
            {
                "confidence": 9.501407763478786,
                "tag": "outdoor"
            },
            {
                "confidence": 9.369449944954914,
                "tag": "wilderness"
            },
            {
                "confidence": 9.360420601701462,
                "tag": "vacation"
            },
            {
                "confidence": 9.296071412602751,
                "tag": "rocks"
            },
            {
                "confidence": 9.200920445068395,
                "tag": "high"
            },
            {
                "confidence": 9.098263071652019,
                "tag": "highland"
            },
            {
                "confidence": 8.913046059906952,
                "tag": "tourist"
            },
            {
                "confidence": 8.871845404715511,
                "tag": "hike"
            },
            {
                "confidence": 8.849417942778766,
                "tag": "landmark"
            },
            {
                "confidence": 8.696960631180973,
                "tag": "cliff"
            },
            {
                "confidence": 8.600540480067334,
                "tag": "scene"
            },
            {
                "confidence": 8.5361026189036,
                "tag": "stream"
            },
            {
                "confidence": 8.530218748458173,
                "tag": "sunny"
            },
            {
                "confidence": 8.25512938559187,
                "tag": "altitude"
            },
            {
                "confidence": 8.016431852333445,
                "tag": "trail"
            },
            {
                "confidence": 7.994086164068538,
                "tag": "autumn"
            },
            {
                "confidence": 7.985516370064935,
                "tag": "california"
            },
            {
                "confidence": 7.927747027669138,
                "tag": "spain"
            },
            {
                "confidence": 7.774262139883552,
                "tag": "adventure"
            },
            {
                "confidence": 7.560366727860158,
                "tag": "peaceful"
            },
            {
                "confidence": 7.486045584679369,
                "tag": "fall"
            },
            {
                "confidence": 7.284083082298321,
                "tag": "erosion"
            },
            {
                "confidence": 7.272279484388568,
                "tag": "terrain"
            },
            {
                "confidence": 7.245267614910601,
                "tag": "rural"
            },
            {
                "confidence": 7.2351406178728555,
                "tag": "vista"
            },
            {
                "confidence": 7.092504717123412,
                "tag": "holiday"
            }
        ]
    }
]
}

After we have signed up and have our credentials, let's try making our first request to the /tagging endpoint now.

When we check the specification of the endpoint, we find that it accepts only GET requests and we can either directly submit a URL for analyzing or upload an image file to the API's /content endpoint, and use the upload identifier to submit the image for tagging with the tagging's content parameter. In this example we will use just a URL of an image. Let's try with the following one:

In the code section we can see how to make the request and what a successful response would look like.

3. Have fun!

Explore the other amazing features of Imagga API and have fun building great things with image recognition.

Authentication

Here’s is how to set up the basic authentication:

# With shell, you can just pass the correct header with each request
curl api_endpoint_here" -H "Authorization: Basic YWNjX2R1bW15OmR1bW15X3NlY3JldF9jb2RlXzEyMzQ1Njc4OQ=="

# Or you can use the user parameter and just specify your api key and secret
curl "api_endpoint_here" --user "<api_key>:<api_secret>"
import requests

api_key = ''
api_secret = ''

response = requests.get('https://api.imagga.com/v1',
                        auth=(api_key, api_secret))
<?php

$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

// Some result handling goes here ...
String apiKey = "",
       apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1")
    .basicAuth(apiKey, apiSecret)
    .asJson();

// Do some result handling here...
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get 'https://api.imagga.com/v1', { :Authorization => auth }
puts response
var request = require('request'),
    apiKey = '',
    apiSecret = '';

request.get('https://api.imagga.com/v1', function (error, response, body) {
    console.log('Status:', response.statusCode);
    console.log('Headers:', JSON.stringify(response.headers));
    console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    api_key := ""
    api_secret := ""

    req, _ := http.NewRequest("GET", "https://api.imagga.com/v1", nil)
    req.SetBasicAuth(api_key, api_secret)

    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Error when sending request to the server")
        return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));
            }
        }
    }
}

Make sure to replace the api key and secret with your API credentials which can be found in your dashboard.

Currently the only supported method for authentication is Basic. In order to be able to use our APIs you should first Sign Up to receive your very own api key and secret pair. You shouldn’t disclose them to anyone. The api key will serve as your username in the Basic authentication process and the api secret will be your password.

The Basic authentication requires you to provide an “Authorization” header with each request beginning with the word "Basic" followed by an interval and your api key and secret in the form api_key:api_secret base64 encoded.

Versioning

The versioning of the API is specified as part of the URI. For instance, in order to use v1 of the API the request URI should begin with /v1 followed by a specific endpoint.

https://api.imagga.com/v1

API Endpoints

/tagging

Request:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/tagging?url=https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg
import requests

api_key = ''
api_secret = ''
image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg'

response = requests.get('https://api.imagga.com/v1/tagging?url=%s' % image_url,
                        auth=(api_key, api_secret))

print response.json()
<?php

$image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg';
$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/tagging?url='.urlencode($image_url));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String imageUrl = "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg",
apiKey = "",
apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/tagging")
    .queryString("url", imageUrl)
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get "https://api.imagga.com/v1/tagging?url=#{image_url}", { :Authorization => auth }
puts response
var request = require('request'),
    apiKey = '',
    apiSecret = '',
    imageUrl = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg';

request.get('https://api.imagga.com/v1/tagging?url='+encodeURIComponent(imageUrl), function (error, response, body) {
    console.log('Status:', response.statusCode);
    console.log('Headers:', JSON.stringify(response.headers));
    console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1/tagging?url=http%3A%2F%2Fimagga.com%2Fstatic%2Fimages%2Ftagging%2Fwind-farm-538576_640.jpg"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    api_key := ""
    api_secret := ""
    image_url := "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg"

    req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/tagging?url="+image_url, nil)
    req.SetBasicAuth(api_key, api_secret)

    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Error when sending request to the server")
        return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";
            string imageUrl = "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Accept.Clear ();
                client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

                HttpResponseMessage response = await client.GetAsync (String.Format("tagging?url={0}", imageUrl));

                HttpContent content = response.Content;
                string result = await content.ReadAsStringAsync ();
                Console.WriteLine (result);
            }
        }
    }
}
Example Response:
{
    "results": [
        {
            "tagging_id": null,
            "image": "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg",
            "tags": [
                {
                    "confidence": 38.51164403389053,
                    "tag": "sky"
                },
                {
                    "confidence": 25.775729223221116,
                    "tag": "turbine"
                },
                {
                    "confidence": 20.417771132010046,
                    "tag": "landscape"
                },
                {
                    "confidence": 20.042762638919744,
                    "tag": "energy"
                },
                {
                    "confidence": 18.497240372029644,
                    "tag": "power"
                },
                {
                    "confidence": 17.489144330962123,
                    "tag": "water"
                },
                {
                    "confidence": 15.917090268364639,
                    "tag": "generator"
                },
                {
                    "confidence": 15.310259589939346,
                    "tag": "clouds"
                },
                {
                    "confidence": 15.165150940330252,
                    "tag": "environment"
                },
                {
                    "confidence": 14.997479700546895,
                    "tag": "electricity"
                },
                {
                    "confidence": 14.778239958946969,
                    "tag": "summer"
                },
                {
                    "confidence": 14.334381229181048,
                    "tag": "travel"
                },
                {
                    "confidence": 13.595784810394616,
                    "tag": "cloud"
                },
                {
                    "confidence": 12.689286103162258,
                    "tag": "industry"
                },
                {
                    "confidence": 12.474390970683636,
                    "tag": "sun"
                },
                {
                    "confidence": 12.428481363081724,
                    "tag": "wind"
                },
                {
                    "confidence": 12.2996585146427,
                    "tag": "grass"
                },
                {
                    "confidence": 12.16,
                    "tag": "solar dish"
                },
                {
                    "confidence": 11.155735242880166,
                    "tag": "industrial"
                },
                {
                    "confidence": 10.92431430854543,
                    "tag": "business"
                },
                {
                    "confidence": 10.922887690131743,
                    "tag": "tower"
                },
                {
                    "confidence": 10.720659875946499,
                    "tag": "architecture"
                },
                {
                    "confidence": 10.538643934032613,
                    "tag": "technology"
                },
                {
                    "confidence": 10.475420949778126,
                    "tag": "windmill"
                },
                {
                    "confidence": 10.184973873695311,
                    "tag": "alternative"
                },
                {
                    "confidence": 10.112964889061951,
                    "tag": "sea"
                },
                {
                    "confidence": 10.067209119467698,
                    "tag": "ocean"
                },
                {
                    "confidence": 9.896929042614056,
                    "tag": "light"
                },
                {
                    "confidence": 9.756266840411426,
                    "tag": "sunny"
                },
                {
                    "confidence": 9.710600089432106,
                    "tag": "reflector"
                },
                {
                    "confidence": 9.681384894667582,
                    "tag": "outdoors"
                },
                {
                    "confidence": 9.541597967167279,
                    "tag": "building"
                },
                {
                    "confidence": 9.53210902788611,
                    "tag": "day"
                },
                {
                    "confidence": 9.497780606866497,
                    "tag": "field"
                },
                {
                    "confidence": 9.3626861012609,
                    "tag": "outdoor"
                },
                {
                    "confidence": 9.120627821594463,
                    "tag": "electric"
                },
                {
                    "confidence": 9.112980153006824,
                    "tag": "urban"
                },
                {
                    "confidence": 8.93623054131651,
                    "tag": "boat"
                },
                {
                    "confidence": 8.528651279443462,
                    "tag": "vacation"
                },
                {
                    "confidence": 8.382439209874228,
                    "tag": "structure"
                },
                {
                    "confidence": 8.357077300251976,
                    "tag": "environmental"
                },
                {
                    "confidence": 8.300176474894023,
                    "tag": "scene"
                },
                {
                    "confidence": 8.083176336292826,
                    "tag": "beach"
                },
                {
                    "confidence": 7.888729554299391,
                    "tag": "city"
                },
                {
                    "confidence": 7.8576389198181475,
                    "tag": "mill"
                },
                {
                    "confidence": 7.810005879114551,
                    "tag": "transportation"
                },
                {
                    "confidence": 7.736862242395749,
                    "tag": "sunlight"
                },
                {
                    "confidence": 7.7354458908851385,
                    "tag": "tourism"
                },
                {
                    "confidence": 7.713032414117088,
                    "tag": "metal"
                },
                {
                    "confidence": 7.519140552569494,
                    "tag": "high"
                },
                {
                    "confidence": 7.506408081999852,
                    "tag": "antenna"
                },
                {
                    "confidence": 7.484635742049309,
                    "tag": "line"
                },
                {
                    "confidence": 7.456804947210837,
                    "tag": "holiday"
                },
                {
                    "confidence": 7.44412567213686,
                    "tag": "ship"
                },
                {
                    "confidence": 7.332463294892768,
                    "tag": "hill"
                },
                {
                    "confidence": 7.213330446567677,
                    "tag": "global"
                },
                {
                    "confidence": 7.108260259076384,
                    "tag": "road"
                }
            ]
        }
    ]
}

GET https://api.imagga.com/v1/tagging

Our Auto-Tagging Solution harnesses the power of state-of-the-art technologies for image understanding in order to provide you with the most advanced and powerful automatic tagging through an easy to use REST interface.

By sending image URLs to the /tagging endpoint you can get a list of many automatically suggested textual tags. Confidence percentage will be assigned to each of them so you can filter only the most relevant ones for your specific case.

Query Parameters

Parameter Description
url Image URL to perform auto-tagging on. You can provide up to 5 urls for processing by sending multiple url parameters (e.g. ?url=<first_url>&url=<second_url>…&url=<nth_url>)
content You can also directly send image files for auto-tagging by uploading them to our /content endpoint and then providing the received content identifiers via this parameter. As with the url parameter you can send more than one image - up to 5 content ids by sending multiple “content” parameters.
language (default: en) If you’d like to get a translation of the tags in other languages, you should use the language parameter. Its value should be the code of the language you’d like to receive tags in. Again, you can apply this parameter multiple times to request tags translated in several languages. See all available languages here.
verbose (default: 1) Whether to return some additional information about each of the tags (such as WordNet synset id for some of them) or not.

Response Description

The response from the tagging is a JSON object which may have 2 main keys. The first one is the `results` key under which (as you may have expected) you will find an array of the tagging results for every successfully analysed image. Each of the results is a JSON object on it’s own with the following data:

If the processing was unsuccessful, you will find the reason under the `unsuccessful` item of the JSON response. Here expect another array of objects, each having the following 2 keys:

/categorizers

Request:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/categorizers
import requests

api_key = ''
api_secret = ''

response = requests.get('https://api.imagga.com/v1/categorizers',
auth=(api_key, api_secret))

print response.json()
<?php

$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/categorizers');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String apiKey = "",
apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/categorizers")
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get 'https://api.imagga.com/v1/categorizers', { :Authorization => auth }
puts response
var request = require('request'),
    apiKey = '',
    apiSecret = '';

request.get('https://api.imagga.com/v1/categorizers', function (error, response, body) {
    console.log('Status:', response.statusCode);
    console.log('Headers:', JSON.stringify(response.headers));
    console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1/categorizers"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    api_key := ""
    api_secret := ""

    req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/categorizers", nil)
    req.SetBasicAuth(api_key, api_secret)

    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Error when sending request to the server")
        return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
            client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
            client.DefaultRequestHeaders.Accept.Clear ();
            client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
            client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

            HttpResponseMessage response = await client.GetAsync (String.Format("categorizers"));

            HttpContent content = response.Content;
            string result = await content.ReadAsStringAsync ();
            Console.WriteLine (result);
            }
        }
    }
}
Example Response:
[
    {
        "labels": [
            "interior objects",
            "nature landscape",
            "beaches seaside",
            "events parties",
            "food drinks",
            "paintings art",
            "pets animals",
            "text visuals",
            "sunrises sunsets",
            "cars vehicles",
            "macro flowers",
            "streetview architecture",
            "people portraits"
        ],
        "id": "personal_photos",
        "title": "Personal Photos Categorizer"
    },
    {
        "labels": [
            "nsfw",
            "safe",
            "underwear"
        ],
        "id": "nsfw_beta",
        "title": "NSFW Categorizer (beta v2)"
    }
]

GET https://api.imagga.com/v1/categorizers

Get a list of all available categorizers for you.

A categorizer is used to recognize various objects and concepts. There are several predefined ones available but if none of them fit your needs we can build a custom one for you.

Response Description

When a request to the `/categorizers` endpoint is made, the API responds with a JSON array of objects each of which describing a categorizer that you have access to, with the following data:

/categorizations/<categorizer_id>

Request:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/categorizations/personal_photos?url=https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg
import requests

api_key = ''
api_secret = ''
image_url = 'https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg'
categorizer_id = 'personal_photos'

response = requests.get('https://api.imagga.com/v1/categorizations/%s?url=%s' % (categorizer_id, image_url),
auth=(api_key, api_secret))

print response.json()
<?php

$image_url = 'https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg';
$categorizer = 'personal_photos';

$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/categorizations/'.$categorizer.'?url='.urlencode($image_url));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String imageUrl = "https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg",
       apiKey = "",
       apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/categorizations/personal_photos")
    .queryString("url", imageUrl)
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_url = 'https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg'
categorizer = 'personal_photos'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get "https://api.imagga.com/v1/categorizations/#{categorizer}?url=#{image_url}", { :Authorization => auth }
puts response
var request = require('request'),
    apiKey = '',
    apiSecret = '',
    imageUrl = 'https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg';

request.get('https://api.imagga.com/v1/categorizations/personal_photos?url='+encodeURIComponent(imageUrl), function (error, response, body) {
    console.log('Status:', response.statusCode);
    console.log('Headers:', JSON.stringify(response.headers));
    console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1/categorizations/personal_photos?url=https%3A%2F%2Fimagga-com-assets.azureedge.net%2Fstatic%2Fimages%2Fcategorization%2Fskyline-14619_640.jpg"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    api_key := ""
    api_secret := ""
    image_url := "https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpgg"

    req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/categorizations/personal_photos?url="+image_url, nil)
    req.SetBasicAuth(api_key, api_secret)

    resp, err := client.Do(req)

    if err != nil {
    fmt.Println("Error when sending request to the server")
    return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";
            string imageUrl = "https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg";
            string categorizerId = "personal_photos";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Accept.Clear ();
                client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

                HttpResponseMessage response = await client.GetAsync (String.Format("categorizations/{0}?url={1}", categorizerId, imageUrl));

                HttpContent content = response.Content;
                string result = await content.ReadAsStringAsync ();
                Console.WriteLine (result);
            }
        }
    }
}
Example Response:
{
    "results": [
        {
            "image": "https://imagga-com-assets.azureedge.net/static/images/categorization/skyline-14619_640.jpg",
            "categories": [
                {
                    "confidence": 99.85,
                    "name": "streetview architecture"
                },
                {
                    "confidence": 0.08,
                    "name": "nature landscape"
                }
            ]
        }
    ]
}

GET https://api.imagga.com/v1/categorizations/<categorizer_id>

As soon as you have decided which is the best categorizer for your images or have trained your own, you are ready to get your hands dirty with some photo classification. You can get a list of the available ones using the /categorizers endpoint or you can find them in the next section of this documentation.

Sending an image for classification is really easy. It can be achieved with a simple GET request to this endpoint. If the classification is successful, as a result, you will get back 200 (OK) response and a list of categories, each with a confidence percentage specifying how confident the system is about the particular result.

Query Parameters

Parameter Description
url URL of an image to submit for categorization. You can provide up to 10 urls for processing by sending multiple url parameters (e.g. ?url=<first_url>&url=<second_url>…&url=<nth_url>)
content You can also directly send image files for categorization by uploading the images to our /content endpoint and then providing the received content identifiers via this parameter. As with the url parameter you can send more than one image - up to 10 content ids by sending multiple “content” parameters.
language (default: en) If you’d like to get a translation of the tags in other languages, you should use the language parameter. Its value should be the code of the language you’d like to receive tags in. Again, you can apply this parameter multiple times to request tags translated in several languages. See all available languages here.

Response Description

The response of this API call would be a JSON object containing 2 main keys. The first one is a `results` array of the categorization results for every successfully categorized image. Each categorization result here would be a JSON object with the following data:

If the categorization was unsuccessful you will find the reason under the `unsuccessful` array with the following keys:

/croppings

Request:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/croppings?url=https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg&resolution=500x300&resolution=100x100&resolution=350x200
import requests

api_key = ''
api_secret = ''
image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg'

response = requests.get('https://api.imagga.com/v1/croppings?url=%s&resolution=100x100&resolution=500x300' % image_url,
                        auth=(api_key, api_secret))

print response.json()
<?php

$image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg';
$sizes = array(
    '100x100',
    '350x200',
    '500x300'
);
$resolutions_params = array();

foreach ( $sizes as $size ) {
    $resolutions_params[] = 'resolution='.$size;
}

$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/croppings?url=' . urlencode($image_url) . '&' . implode('&', $resolutions_params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String imageUrl = "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg",
       apiKey = "",
       apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/croppings")
    .queryString("url", imageUrl)
    .queryString("resolution", "100x100")
    .queryString("resolution", "500x300")
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get "https://api.imagga.com/v1/croppings?url=#{image_url}", { :Authorization => auth }
puts response
var request = require('request'),
    apiKey = '',
    apiSecret = '',
    imageUrl = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg';

request.get('https://api.imagga.com/v1/croppings?url='+encodeURIComponent(imageUrl)+'&resolution=100x100&resolution=500x300&resolution=350x200',
    function (error, response, body) {
        console.log('Status:', response.statusCode);
        console.log('Headers:', JSON.stringify(response.headers));
        console.log('Response:', body);
    }).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1/croppings?url=http%3A%2F%2Fimagga.com%2Fstatic%2Fimages%2Ftagging%2Fwind-farm-538576_640.jpg&resolution=100x100&resolution=500x300"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    api_key := ""
    api_secret := ""
    image_url := "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg"

    req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/croppings?url="+image_url+"&resolution=100x100&resolution=500x300", nil)
    req.SetBasicAuth(api_key, api_secret)

    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Error when sending request to the server")
        return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";
            string imageUrl = "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg";
            string[] resolutions = new string[] { "100x100", "500x300" };

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Accept.Clear ();
                client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

                HttpResponseMessage response = await client.GetAsync (String.Format("croppings?url={0}&resolution={1}&resolution={2}", imageUrl, resolutions[0], resolutions[1]));

                HttpContent content = response.Content;
                string result = await content.ReadAsStringAsync ();
                Console.WriteLine (result);
            }
        }
    }
}
Example Response:
{
    "results": [
        {
            "image": "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg",
            "croppings": [
                {
                    "y2": 448,
                    "target_width": 100,
                    "x2": 513,
                    "target_height": 100,
                    "y1": 0,
                    "x1": 65
                },
                {
                    "y2": 384,
                    "target_width": 500,
                    "x2": 639,
                    "target_height": 300,
                    "y1": 0,
                    "x1": 0
                }
            ]
        }
    ],
    "unsuccessful": []
}

GET https://api.imagga.com/v1/croppings

The technology behind this endpoint analyzes the pixel content of each given image in order to find the most “visually important” areas in the image. Having this information and eventually some constraints, it can suggest the best cropping automatically.

You can perform smart-cropping analysis over a list of URLs and return the coordinates for cropping each of the images. You can send just one URL or several at once.

Query Parameters

Parameter Description
url A URL of the image to send for smart-cropping analysis. You can provide as many url parameters as you like in order to send multiple images for smart-cropping analysis. (e.g. <api_endpoint>?url=<first_url>&url=<second_url>…&url=<nth_url>)
content You can also directly send image files for smart-cropping analysis by uploading them to our /content endpoint and then providing the received content identifier via this parameter. As with the url parameter you can send more than one image - up to 10 content ids by sending multiple "content” parameters.
resolution Resolution pair in the form (width)x(height) where ‘x’ is just the small letter x. You can provide several resolutions just by providing several resolution parameters as with the urls. If you omit this parameter, the API will still suggest the best cropping coordinates so everything that matters in the photo scene is preserved.
no_scaling (default: 0) Whether the cropping coordinates should exactly match the requested resolutions or just preserve their aspect ratios and let you resize the cropped image later. If set to 1, the coordinates that the API is going to return would exactly match the requested resolution so there won't be a need to perform any scaling of the image after cropping it. Otherwise, after cropping the images with the suggested coordinates, you should resize them to the desired resolution.

Response Description

The response from the cropping is a JSON object which may have 2 main keys. The first one is the `results` array where you will find the cropping results for each successfully analysed image. Each of the result objects contains the following 2 keys:

If the cropping was unsuccessful you will find the reason under the `unsuccessful` item of the JSON response. Here expect another array of objects, each having the following two keys:

When only a cropping for a certain resolution fails, the object under the `unsuccessful` array would have 2 more items describing the resolution that has failed and these are:

/colors

Request:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/colors?url=https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg
import requests

api_key = ''
api_secret = ''
image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg'

response = requests.get('https://api.imagga.com/v1/colors?url=%s' % image_url,
auth=(api_key, api_secret))

print response.json()
<?php

$image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg';

$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/colors?url='.urlencode($image_url));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String imageUrl = "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg",
apiKey = "",
apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/colors")
    .queryString("url", imageUrl)
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_url = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get "https://api.imagga.com/v1/colors?url=#{image_url}", { :Authorization => auth }
puts response
var request = require('request'),
    apiKey = '',
    apiSecret = '',
    imageUrl = 'https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg';

request.get('https://api.imagga.com/v1/colors?url='+encodeURIComponent(imageUrl), function (error, response, body) {
    console.log('Status:', response.statusCode);
    console.log('Headers:', JSON.stringify(response.headers));
    console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1/colors?url=http%3A%2F%2Fimagga.com%2Fstatic%2Fimages%2Ftagging%2Fwind-farm-538576_640.jpg"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    api_key := ""
    api_secret := ""
    image_url := "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg"

    req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/colors?url="+image_url, nil)
    req.SetBasicAuth(api_key, api_secret)

    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Error when sending request to the server")
        return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";
            string imageUrl = "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Accept.Clear ();
                client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

                HttpResponseMessage response = await client.GetAsync (String.Format("colors?url={0}", imageUrl));

                HttpContent content = response.Content;
                string result = await content.ReadAsStringAsync ();
                Console.WriteLine (result);
            }
        }
    }
}
Example Response:
{
    "results": [
        {
            "info": {
                "background_colors": [
                    {
                        "b": "146",
                        "g": "121",
                        "closest_palette_distance": 6.607301706546877,
                        "closest_palette_color_parent": "blue",
                        "r": "82",
                        "html_code": "#527992",
                        "closest_palette_color_html_code": "#6e7e99",
                        "closest_palette_color": "larkspur",
                        "percentage": 48.68
                    },
                    {
                        "b": "46",
                        "g": "90",
                        "closest_palette_distance": 2.002274829533564,
                        "closest_palette_color_parent": "skin",
                        "r": "137",
                        "html_code": "#895a2e",
                        "closest_palette_color_html_code": "#8c5e37",
                        "closest_palette_color": "light bronze",
                        "percentage": 40.74
                    },
                    {
                        "b": "36",
                        "g": "54",
                        "closest_palette_distance": 6.404418053708967,
                        "closest_palette_color_parent": "brown",
                        "r": "82",
                        "html_code": "#523624",
                        "closest_palette_color_html_code": "#584039",
                        "closest_palette_color": "brownie",
                        "percentage": 10.58
                    }
                ],
                "color_variance": "36",
                "object_percentage": "2.30",
                "image_colors": [
                    {
                        "b": "45",
                        "g": "83",
                        "percent": 51.68,
                        "closest_palette_color_parent": "skin",
                        "r": "126",
                        "html_code": "#7e532d",
                        "closest_palette_color_html_code": "#7c5a2c",
                        "closest_palette_color": "medium brown",
                        "closest_palette_distance": 4.145651666822428
                    },
                    {
                        "b": "145",
                        "g": "121",
                        "percent": 48.22,
                        "closest_palette_color_parent": "blue",
                        "r": "83",
                        "html_code": "#537991",
                        "closest_palette_color_html_code": "#6e7e99",
                        "closest_palette_color": "larkspur",
                        "closest_palette_distance": 6.643697722134033
                    }
                ],
                "color_percent_threshold": 1.75,
                "foreground_colors": [
                    {
                        "b": "52",
                        "g": "69",
                        "closest_palette_distance": 2.5701833132187457,
                        "closest_palette_color_parent": "brown",
                        "r": "98",
                        "html_code": "#624534",
                        "closest_palette_color_html_code": "#5d473a",
                        "closest_palette_color": "latte",
                        "percentage": 53.99
                    },
                    {
                        "b": "136",
                        "g": "156",
                        "closest_palette_distance": 4.741182409559405,
                        "closest_palette_color_parent": "light brown",
                        "r": "181",
                        "html_code": "#b59c88",
                        "closest_palette_color_html_code": "#b09080",
                        "closest_palette_color": "cappuccino",
                        "percentage": 29.24
                    },
                    {
                        "b": "39",
                        "g": "40",
                        "closest_palette_distance": 6.083666083751362,
                        "closest_palette_color_parent": "black",
                        "r": "47",
                        "html_code": "#2f2827",
                        "closest_palette_color_html_code": "#3a3536",
                        "closest_palette_color": "graphite",
                        "percentage": 16.77
                    }
                ]
            },
            "image": "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg"
        }
    ],
    "unsuccessful": []
}

GET https://api.imagga.com/v1/colors

Analyse and extract the predominant colors from one or several images.

Query Parameters

Parameter Description
url Image URL to perform color extraction on. You can provide as many url parameters as you like in order to send multiple images for color extraction. (e.g. <api_endpoint>?url=<first_url>&url=<second_url>…&url=<nth_url>)
content You can also send actual image files for color extraction. This is achieved by uploading the images to our /content endpoint and then providing the received content identifier via this parameter. As with the url parameter you can send more than one image - up to 10 content ids by sending multiple “content” parameters.
extract_overall_colors (default: 1) Specify whether the overall image colors should be extracted. The possible values are 1 for 'yes’, and 0 for 'no’.
extract_object_colors (default: 1) Specify if the service should try to extract object and non-object (a.k.a. foreground and background) colors separately. The possible values are 1 for 'yes’, and 0 for 'no’.

Response Description

The response of the `/colors` endpoint is a JSON object which may have 2 main keys. The first one is the `results` array where you will find the color results for every successfully analysed image. Each of the color extraction results is a JSON object with the following data:

If the /colors API call was unsuccessful you will find the reason under the `unsuccessful` array with the following keys:

/content(/<content_id>)

Request:

The following snippet demonstrates how to upload an image to the /content endpoint.

curl --user "<your-api-key>:<your-api-secret>" -F "image=@/path/to/image.jpg" https://api.imagga.com/v1/content
import requests

api_key = ''
api_secret = ''
image_path = '/path/to/your/image.jpg'

response = requests.post('https://api.imagga.com/v1/content',
auth=(api_key, api_secret),
files={'image': open(image_path, 'r')})
print response.json()
<?php

$file_path = '/path/to/my/image.jpg';
$api_credentials = array(
    'key' => '',
    'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "http://api.imagga.com/v1/content");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, array('image' => "@'.$file_path.';type=".mime_content_type($file_path)));

curl_setopt($curl, CURLOPT_HEADER, array(
    'Accept: application/json'
));

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String apiKey = "",
       apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.post("https://api.imagga.com/v1/content")
    .basicAuth(apiKey, apiSecret)
    .field("image", new File("/path/to/image.jpg"))
    .asJson();

    JSONObject jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_path = '/path/to/image.jpg'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.post "https://api.imagga.com/v1/content", { :image => File.new(image_path, 'rb') }, { :Authorization => auth }
puts response
var fs = require('fs'),
    request = require('request'),
    apiKey = '',
    apiSecret = '',
    filePath = '/path/to/image.jpg',
    formData = {
        image: fs.createReadStream(filePath)
    };

request.post({url:'https://api.imagga.com/v1/content', formData: formData},
    function (error, response, body) {
        console.log('Status:', response.statusCode);
        console.log('Headers:', JSON.stringify(response.headers));
        console.log('Response:', body);
    }).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};
NSURL* file = nil;
NSDictionary* parameters = @{@"file": file};

UNIUrlConnection *asyncConnection = [[UNIRest post:^(UNISimpleRequest *request) {
    [request setUrl:@"https://api.imagga.com/v1/content"];
    [request setHeaders:headers];
    [request setUsername:@"your-api-key"];
    [request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
    NSInteger code = response.code;
    NSDictionary *responseHeaders = response.headers;
    UNIJsonNode *body = response.body;
    NSData *rawBody = response.rawBody;
}];
package main

import (
    "bytes",
    "fmt",
    "io/ioutil"
    "mime/multipart",
    "net/http"
    "os"
)

func main() {
    var b bytes.Buffer
    w := multipart.NewWriter(&b)

    // Add the image file
    f, err := os.Open('/path/to/image.jpg')

    if err != nil {
        return
    }

    fw, err := w.CreateFormFile("image", file)
    if err != nil {
        return
    }
    w.Close()

    client := &http.Client{}
    api_key := ""
    api_secret := ""
    image_url := "https://imagga.com/static/images/tagging/wind-farm-538576_640.jpg"

    req, _ := http.NewRequest("POST", "https://api.imagga.com/v1/content", &b)
    req.SetBasicAuth(api_key, api_secret)
    req.Header.Set("Content-Type", w.FormDataContentType())

    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Error when sending request to the server")
        return
    }

    defer resp.Body.Close()
    resp_body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(resp.Status)
    fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
            client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
            client.DefaultRequestHeaders.Accept.Clear ();
            client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
            client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

            byte[] file = File.ReadAllBytes ("/path/to/the/image.jpg");

            MultipartFormDataContent uploads = new MultipartFormDataContent ();
            uploads.Add(new ByteArrayContent(file), "image", "image.jpg");

            HttpResponseMessage response = await client.PostAsync ("content", uploads);

            HttpContent content = response.Content;
            string result = await content.ReadAsStringAsync ();
            Console.WriteLine (result);
            }
        }
    }
}
Example Response:
{
    "status": "success",
    "uploaded": [
        {
            "id": "f86af4d8a6f1abec39d828579a6c4004",
            "filename": "image.jpg"
        }
    ]
}

Upload a file

POST https://api.imagga.com/v1/content

Using the /content endpoint you can upload a file (image or video) for processing by one of the other Imagga API endpoint.

After a successful image upload to this endpoint, in the JSON response you will find an upload identifier such as f86af4d8a6f1abec39d828579a6c4004 which could be then submitted to any of the other billable endpoints (tagging, categorization, cropping and colour extraction) via their content parameter.

Response Description

The response of this API call would be a JSON object with the following data:

If the API call was unsuccessful you will get a response with a status having an “error” value and a human-readable description of the failure under the `message` key.

Delete an uploaded file

DELETE https://api.imagga.com/v1/content/<:content_id>

By submitting a DELETE request to the content endpoint with the content identifier at the end of it (e.g. /content/f86af4d8a6f1abec39d828579a6c4004), you can delete a file, you've previously uploaded.

Categorizers

There are several public categorizers available for everybody to use via the /categorizations endpoint. Currently these are:

In the following sections, you can find more information about each of them.

We also offer custom categorization which means we can build a classifier specifically for your case. If there isn't a public categorizer that suit your needs, please let us know.

Personal Photos

With the Personal Photos (personal_photos) categorizer you can sort a collection of photos into predefined set of categories which match the types of photos you will typically find in most of the personal photo collections out there.

Id: personal_photos

Categories:

NSFW Beta

Request:
curl --user "<your-api-key>:<your-api-secret>" https://api.imagga.com/v1/categorizations/nsfw_beta?url=https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg
import requests

api_key = ''
api_secret = ''
image_url = 'https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg'
categorizer_id = 'nsfw_beta'

response = requests.get('https://api.imagga.com/v1/categorizations/%s?url=%s' % (categorizer_id, image_url),
auth=(api_key, api_secret))

print response.json()
<?php

$image_url = 'https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg';
$categorizer = 'nsfw_beta';

$api_credentials = array(
'key' => '',
'secret' => ''
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.imagga.com/v1/categorizations/'.$categorizer.'?url='.urlencode($image_url));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_USERPWD, $api_credentials['key'].':'.$api_credentials['secret']);

$response = curl_exec($ch);
curl_close($ch);

$json_response = json_decode($response);
var_dump($json_response);
String imageUrl = "https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg",
apiKey = "",
apiSecret = "";

// These code snippets use an open-source library. http://unirest.io/java
HttpResponse response = Unirest.get("https://api.imagga.com/v1/categorizations/nsfw_beta")
    .queryString("url", imageUrl)
    .basicAuth(apiKey, apiSecret)
    .header("Accept", "application/json")
    .asJson();

    jsonResponse = response.getBody().getObject();
    System.out.println(jsonResponse.toString());
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
require 'base64'

image_url = 'https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg'
categorizer = 'nsfw_beta'
api_key = ''
api_secret = ''

auth = 'Basic ' + Base64.strict_encode64( "#{api_key}:#{api_secret}" ).chomp
response = RestClient.get "https://api.imagga.com/v1/categorizations/#{categorizer}?url=#{image_url}", { :Authorization => auth }
puts response
var request = require('request'),
apiKey = '',
apiSecret = '',
imageUrl = 'https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg';

request.get('https://api.imagga.com/v1/categorizations/nsfw_beta?url='+encodeURIComponent(imageUrl), function (error, response, body) {
console.log('Status:', response.statusCode);
console.log('Headers:', JSON.stringify(response.headers));
console.log('Response:', body);
}).auth(apiKey, apiSecret, true);
// These code snippets use an open-source library. http://unirest.io/objective-c
NSDictionary *headers = @{@"Accept": @"application/json"};

UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
[request setUrl:@"https://api.imagga.com/v1/categorizations/nsfw_beta?url=https%3A%2F%2Fimagga-com-assets.azureedge.net%2Fstatic%2Fimages%2Fnsfw%2Fgirl-1211435_960_720.jpg"];
[request setHeaders:headers];
[request setUsername:@"your-api-key"];
[request setPassword:@"your-api-secret"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
NSInteger code = response.code;
NSDictionary *responseHeaders = response.headers;
UNIJsonNode *body = response.body;
NSData *rawBody = response.rawBody;
}];
package main

import (
"fmt"
"io/ioutil"
"net/http"
)

func main() {
client := &http.Client{}
api_key := ""
api_secret := ""
image_url := "https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg"

req, _ := http.NewRequest("GET", "https://api.imagga.com/v1/categorizations/nsfw_beta?url="+image_url, nil)
req.SetBasicAuth(api_key, api_secret)

resp, err := client.Do(req)

if err != nil {
fmt.Println("Error when sending request to the server")
return
}

defer resp.Body.Close()
resp_body, _ := ioutil.ReadAll(resp.Body)

fmt.Println(resp.Status)
fmt.Println(string(resp_body))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;


namespace ImaggaAPISample
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            RunAsync ().Wait ();
        }

        static async Task RunAsync()
        {
            string apiKey = "<replace-with-your-api-key>";
            string apiSecret = "<replace-with-your-api-key>";
            string imageUrl = "https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg";
            string categorizerId = "nsfw_beta";

            string basicAuthValue = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes (String.Format ("{0}:{1}", apiKey, apiSecret)));

            using (var client = new HttpClient ()) {
                client.BaseAddress = new Uri ("https://api.imagga.com/v1/");
                client.DefaultRequestHeaders.Accept.Clear ();
                client.DefaultRequestHeaders.Accept.Add (new MediaTypeWithQualityHeaderValue ("application/json"));
                client.DefaultRequestHeaders.Add ("Authorization", String.Format("Basic {0}", basicAuthValue));

                HttpResponseMessage response = await client.GetAsync (String.Format("categorizations/{0}?url={1}", categorizerId, imageUrl));

                HttpContent content = response.Content;
                string result = await content.ReadAsStringAsync ();
                Console.WriteLine (result);
            }
        }
    }
}
Example Response:
{
    "results": [
        {
            "image": "https://imagga-com-assets.azureedge.net/static/images/nsfw/girl-1211435_960_720.jpg",
            "categories": [
                {
                    "confidence": 87.03,
                    "name": "underwear"
                },
                {
                    "confidence": 11.69,
                    "name": "nsfw"
                },
                {
                    "confidence": 1.27,
                    "name": "safe"
                }
            ]
        }
    ]
}

The NSFW (Not Safe For Work) beta (nsfw_beta) categorizer allows you to detect pornographic content and all kinds of nudity. The three available categories are nsfw which means pornographic content, underwear which, as the name suggests, detects people in underwear, and safe which should mean there isn't any kind of nudity in the photo.

Id: nsfw_beta

Disclaimer: The classifier is still in beta so you might expect some photos that are not safe (pornographic content) to be classified as "safe". Use with caution.

Multi-Language Support

The auto-tagging and auto-categorization are also multilingual. You can choose other languages in which to get the results via the language parameter with each request.

Currently there are 51 languages supported (including the default one -- English) with the following language codes:

Language Code Language
ar Arabic
bg Bulgarian
bs Bosnian
en (default) English
ca Catalan
cs Czech
cy Welsh
da Danish
de German
el Greek
es Spanish
et Estonian
fa Persian
fi Finnish
fr French
he Hebrew
hi Hindi
hr Croatian
ht Haitian Creole
hu Hungarian
id Indonesian
it Italian
ja Japanese
ko Korean
lt Lithuanian
lv Latvian
ms Malay
mt Maltese
mww Hmong Daw
nl Dutch
no Norwegian
otq Querétaro Otomi
pl Polish
pt Portuguese
ro Romanian
ru Russian
sk Slovak
sv Swedish
sl Slovenian
sr_cyrl Serbian - Cyrillic
sr_latn Serbian - Latin
th Thai
tlh Klingon
tlh_qaak Klingon (pIqaD)
tr Turkish
uk Ukrainian
ur Urdu
vi Vietnamese
yua Yucatec Maya
zh_chs Chinese Simplified
zh_cht Chinese Traditional

Best Practices

Images Size

If your network connection or the network connection of the server where your images are being stored is slow, it is preferable that you downscale the images before sending them to Imagga API. The API doesn't need more that 300px on the shortest side to provide you with the same great results.

Confidence Levels and Results Accuracy

As the tagging is automated, you should know that the technology is far from perfect, yet and it is completely normal to get some irrelevant tags from time to time.

The confidence levels are calculated in such a way to allow you to further refine the final set of tags depending on your case. If getting one or two irrelevant tags from time to time is fine for you and in the same time you prefer having no tags for some of the really challenging images instead of having many irrelevant ones, then our suggestion is setting the confidence threshold at 15-20%. However, if you'd like to be more strict on the accuracy of the tagging results, setting the confidence threshold at 30% might do the trick.

At the end of the day you should know that this is just a suggestion and it all depends on the specific case. Specific confidence levels might be perfectly working for one particular case but completely irrelevant for another. So the best way to determine what will work for you is play around with the API.

Errors

Most of the errors returned by the API would have a response body in the following form:

{
    "status": "error",
    "type": "invalid_authorization",
    "message": "Improperly formatted authorization header."
               "Please consult the documentation at "
               "docs.imagga.com for more information."
}
    

The Imagga API might respond with the following HTTP response codes:

Error Code Meaning
400 Bad Request – Something is wrong with the formatting of your request. Make sure you've provided all required parameters.
401 Unauthorized – There is a problem with the request authorization. Make sure your authorization header is properly formatted with your api key and secret. Read more in the "Authentication" section.
403 Forbidden – You have reached one of your subscription limits therefore you are temporarily not allowed to perform this type of request.
404 Not Found – The endpoint does not exists or you've requested non-existing resource.
405 Method Not Allowed – The HTTP method is not supported by the requested endpoint.
406 Not Acceptable – You requested a format that isn’t json.
410 Gone – The resource you've requested is not available anymore.
429 Too Many Requests – You have reached the concurrency limit of your current subscription plan, just wait a second and retry the request.
500 Internal Server Error – We had a problem with our server. Try again later or write us about this at api [at] imagga.com
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Tutorials

Here are some great tutorials that would hopefully inspire you and help you get started:

Support

Join us on Slack!

Join our Slack server, ask questions and discuss everything AI and image recognition related. Joining us on Slack would:

So what are you waiting for? Get invited now! :) Join us on Slack badge

There are also some other ways to reach to us:

Send us an email

You can write us at api [at] imagga.com

Support Center

Write us through the support center in your imagga.com dashboard.