API documentation

Read more about our API and how to register for it here.

1.  Request

MethodURL
GET / POSThttps://imagerecognize.com/api/v2/
MethodParamsValuesRequired?
GET / POSTapikeystringYes
GET / POSTtypestringYes
POSTfilebinaryYes
POSTmax_labelsint > 0If ‘type’ is ‘objects’
POSTmin_confidence0 <= int <= 100If ‘type’ is ‘objects’
POSTnsfw_min_confidence0 <= int <= 100If ‘type’ is ‘nsfw’

apikey

The apikey is used to validate the request source and must be sent with all client requests. GET request is only allowed together with type ‘cache’.

type

The type is used to identify which part of the recognition engine to use. It must be one of the following string values:

MethodtypeDescription
POSTobjectsIdentify objects using the Object Recognizer
POSTcelebritiesIdentify celebrities using the Celebrities Recognizer
POSTdetect_facesDetect and identify faces using Face Recognizer
POSTdetect_textExtract text using Text Recognizer
POSTnsfwDetect unsafe and NSFW content using NSFW Recognizer
GET / POSTcacheRetrieve cached results from previous API calls

file

The file is the image which is to be analyzed. The image must be in PNG, JPG or JPEG format.

max_labels

The max_labels parameter is used to set the maximum number of detected objects in the response. This parameter is used only for type ‘objects’.

min_confidence

The min_confidence parameter is used to set a lower threshold of confidence detection. In general, a lower number returns more objects. This parameter is used only for type ‘objects’.

nsfw_min_confidence

The nsfw_min_confidence parameter is similar to the min_confidence parameter, but used for the type ‘nsfw’ instead.

2.  Response

An API response consists of 3 main fields:

  • status – HTTP response status code
  • message – A short status message
  • data – The main data object, see Chapter 2.1 for details.

StatusResponse
200{“status”:200,”message”:”Success”,”data”:{“error”:0,”type”:”objects”,”objects”:[{“name”:”Car”,”confidence”:99.87,”coordinates”:[{“x”:0.35″y”:0.88,”width”:0.07,”height”:0.11}]},{“name”:”Pedestrian”,”confidence”:99.81,”coordinates”:[{“x”:0.02,”y”:0.04,”width”:0.82,”height”:0.94}]}],”quota”:3000}}

Your request was analyzed and returned with no errors.
300{“status”:300,”status_message”:”Invalid request, no data received”,”data”:null}

No data was received with your request. Did you call the correct URL? Note the slash at the end after version number.
400{“status”:400,”status_message”:”APIkey missing”,”data”:null}

Your request was sent without an APIKey.
401{“status”:401,”status_message”:”APIkey invalid”,”data”:null}

The passed APIKey is invalid.
402{“status”:402,”status_message”:”Quota limit reached”,”data”:null}

Every account has a preselected quota depending on the API subscription plan. This error will occur if you would exceed this quota.
412{“status”:412,”status_message”:”Invalid file”,”data”:null}

Your request was sent with an invalid coded file.
413{“status”:413,”status_message”:”Image size too large”,”data”:null}

Your request was sent with a too large image. Max size is 50Mb. Contact us if you need a larger limit.
415{“status”:415,”status_message”:”Invalid file format”,”data”:null}

Your request was sent with an invalid file format. Only PNG, JPG and JPEG files are supported.
420{“status”:420,”status_message”:”Invalid type”,”data”:null}

Your request was sent with an invalid parameter type.
430{“status”:430,”status_message”:<…>,”data”:null}

Your request was sent with an invalid or missing parameter for the specified type. See returned status message for details.

2.1  data

A data object will be included in the response if the request was successful. The data object contains the following information:

NameDescription
errorThis is either ‘0’ if there was no error or it contains a brief error description
typeReturns the requested type
objectsThe results containing an array of identified objects
quotaThe quota that is left for use in the account after this response

3.  Example usage

3.1  Python

import requests
import json

API_ENDPOINT = "https://imagerecognize.com/api/v2/"
API_KEY = "YOUR-API-KEY"

with open('image.jpg', 'rb') as f1:
    f = {'file': f1.read()}

d = {'apikey': API_KEY,
     'type': 'objects',
     'max_labels': 10,
     'min_confidence': 80}

r = requests.post(url=API_ENDPOINT, data=d, files=f)

print(r.text)
print(json.loads(r.text))

3.2  HTML/Javascript

<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js">
</script>
<script type="text/javascript">

function send_request() {
    var APIKEY = "YOUR-API-KEY"
    var file_obj = document.getElementById("image-file").files[0];

    var form_data = new FormData();  
    form_data.append('type', 'objects');
    form_data.append('file', file_obj);
    form_data.append('apikey', APIKEY);
    form_data.append('min_confidence', '80');
    form_data.append('max_labels', '10');

    $.ajax({
        type: 'POST',
        url: 'https://imagerecognize.com/api/v2/',
        contentType: false,
        processData: false,
        data: form_data,

        statusCode: {
            402:function() {
                document.getElementById('response1').innerHTML = "402";
            }
        },
        error:function() {
            document.getElementById('response1').innerHTML = "Error";
        },
        success:function(response) {
            document.getElementById('response1').innerHTML = response;
            
            var response_data_JSON = JSON.parse(response)['data'];
            var response_pretty = JSON.stringify(response_data_JSON, undefined, 2)
            document.getElementById('response2').innerHTML = response_pretty
        }
    });
};
</script>
<body>

<input type="file" name="file" id="image-file">
<button onclick="javascript:send_request()" name="submit">Send request</button>

<p id="response1"></p>
<pre id="response2"></pre>

</body>
</html>