API documentation - Image Recognize

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

1. Request

Method	URL
GET / POST	https://imagerecognize.com/api/v3/

Method	Params	Values	Required?
GET / POST	apikey	string	Yes
GET / POST	type	string	Yes
POST	file	binary	Yes
POST	max_labels	int > 0	If ‘type’ is ‘objects’
POST	min_confidence	0 <= int <= 100	If ‘type’ is ‘objects’
POST	nsfw_min_confidence	0 <= int <= 100	If ‘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:

Method	type	Description
POST	objects	Identify objects using the Object Recognizer
POST	celebrities	Identify celebrities using the Celebrities Recognizer
POST	detect_faces	Detect and identify faces using Face Recognizer
POST	detect_text	Extract text using Text Recognizer
POST	nsfw	Detect unsafe and NSFW content using NSFW Recognizer
GET / POST	cache	Retrieve 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.

Status	Response
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 10Mb. 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:

Name	Description
error	This is either ‘0’ if there was no error or it contains a brief error description
type	Returns the requested type
objects	The results containing an array of identified objects
quota	The 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/v3/"
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/v3/',
        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>