Documentation for developers

Introduction

Vize helps you recognize and classify images. It allows you to implement state-of-the-art artificial intelligence into your project simply by using API. You will never have to dive into neural networks and you always get latest visual recognition technology.

After an easy setup, you get highly accurate results for your images and you are ready to build this functionality in your application. It’s easy, quick and highly scalable.

How it works?

Using our web interface, you create categories and upload at least 20 images for each category. We train custom neural network on your specific images and test the accuracy of your model.

You get API key and URL connected to the model. Now you are ready to start using classification in your project. Sending request with an image to our API returns which class fits your image the best.

Before you start

Task is where you start. Each task corresponds to one possible model, set of images and set of categories. You can clone existing tasks if needed. Only you can access your tasks.

Model is the brain behind your image recognition API. Its a neural network trained on your specific images and thus highly accurate at recognizing new images. Each model has its accuracy given at the end of training. Model is private only for its owner.

Categories could be simple “contains car” and “doesn’t contain car” or you can define more categories depending on your needs (red shirt, blue shirt, red trousers, blue trousers).

For each of the categories, you upload images which are then used to train your custom model. Before training of the model, we split your images into training images and testing images. Training images are used for training and few testing images taken aside are used to evaluate the accuracy of the model.

The accuracy of the model is number describing how accurately is your image categorized. Accuracy 95% means 95 of 100 images will match its category. Accuracy depends on a number of images uploaded for training and will not be very accurate for a low number of training images.

Best practises

Neural networks are a powerful technology for image classification. However, we recommend following these best practice rules to get the best results.

  • For the training use variety of images, different focuses on an object and pictures taken from different angles. Do not mix images of different categories (only apples in apple category). Use images that describe best your category.

  • Use many images to train. Minimum is 20 images per category but more images you upload better results you get.

  • Resize your image before you send it to API endpoint. File upload takes most of the time in your API call and we recommend reducing image size to 400px on the shorter side. Our endpoint will accept png and jpg images up to 3MB, but a significant time of your request will be spent on image upload.

API Reference

We provide you a simple RESTful API endpoint. Sample code snippets:

cURL

Use POST method with parameter "image" to http://cl-api.vize.it/YOUR_TASK_ID. To authenticate yourself use a JWT token given after training (keep JWT secret).

cURL code example:
curl -v -XPOST -H 'Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1aWQiOjE4OCwiZXhwIjod25lcl9ieXBhc3MiOnRydWUsImlhdCI6MTQ5MTQwMDYzMn0.XSnNgzMCBRQ6RgIXfc7g39zLvcugmchkL1qjyhXPr8Y' -F 'image=@mypicture.jpg;type=image/jpeg' http://cl-api.vize.it/24310

Python

Use requests package to classify the image. Use POST method with parameter "image" to http://cl-api.vize.it/YOUR_TASK_ID. To authenticate yourself use a JWT token given after training (keep JWT secret).

Python code example:
import requests

url = "http://cl-api.vize.it/20452"   #replace with your task link
files = {'image': open(YOUR_IMAGE, 'rb')} #use path to your image

headers = {"Authorization": "JWT eyJ0eXAiOiJKV1wNX0.UrouAyF65-AX5SVYbDVw9u2RbR6ssYyKjk"} #use your JWT

response = requests.request("POST", url, files=files, headers=headers)
print(response.text)

PHP

Use cURL integration to classify the image. Use POST method with parameter "image" to http://cl-api.vize.it/YOUR_TASK_ID. To authenticate yourself use a JWT token given after training (keep JWT secret).

PHP code example:
$file_name_with_full_path = realpath('photo.png'); //use path to your image
$curl_handle = curl_init("http://cl-api.vize.it/282");    //replace with your task link

curl_setopt($curl_handle, CURLOPT_POST, 1);
$args['image'] = new CurlFile($file_name_with_full_path, 'image/png');
curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $args);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl_handle, CURLOPT_HTTPHEADER, array(
    "authorization: JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1aWQiOjE2NCwiZXhwIjoxNDk5MjAyNDA1LCJvd25lcl9ieXBhc3MiOnRydWUsImlhdCI6MTQ5MTQyNjQwNX0.UrouAyF0T65-AX5SVYbDVw9u2RcWuCHMRbR6ssYyKjk",  //#use your JWT
    "cache-control: no-cache",));

//execute the API Call
$returned_data = curl_exec($curl_handle);
curl_close ($curl_handle);
echo $returned_data;

Authentication

User authentication is done through JWT token sent in the header of POST call. Always keep your JWT secret. Your JWT is generated after first model training and you can always find it in your task details.

API Responses

As a response to your call, you will get a formatted string with results or error message.

Status codes

Number Value
200 OK Returns JSON formatted string
400 BAD REQUEST Returns JSON formatted string
429 TOO MANY REQUESTS Returns HTML formatted string
200 OK - Returns JSON formatted string
{
    "cached": true,
    "classification_time": 0.1728501319885254,
    "classifier_load_time": 5.9604644775390625e-06,
    "prediction": "Audience",
    "preprocess_time": 0.030581951141357422,
    "scores": {
        "Audience": 0.7789751887321472,
        "Stage": 0.22102473676204681
  }
}

##Key description:###

"cached" # - true (model is loaded in server cache) false (model just loaded into cache)
"classification_time" # - time of classification in seconds
"classifier_load_time" # - time of loading model into server cache (if loaded this value is << 1ms)
"prediction": # - predicted class
"preprocess_time" # - time of preprocessing in seconds
"scores": # - lists of all classes and their probability
}
400 BAD REQUEST - Returns JSON formatted string
{
  "message": "Missing image"
}
400 BAD REQUEST - Returns JSON formatted string
{
  "message": "invalid image type or size" #jpg and png, max size 3MB
}

Supported images are jpg and png and maximum size of image is 3 MB.,

429 TOO MANY REQUESTS - Returns HTML formatted string
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>429 Too Many Requests</title>
<h1>Too Many Requests</h1>
<p>1 per 5 second</p>Handling responses

Support

Please, feel free to contact us in case you need any help.
Contact us