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.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

cURL code example:
curl -v -XPOST -H 'Authorization: JWT {your JWT token}' -F 'image=@myimage.jpg;type=image/jpeg' http://cl-api.vize.ai/{your task ID}

Python

Use requests package to classify the image. Use POST method with parameter "image" to http://cl-api.vize.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

Python code example:
import requests

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

headers = {"Authorization": "JWT {your JWT token}"} #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.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

PHP code example:
$file_name_with_full_path = realpath('{myimage.jpg}'); //use path to your image
$curl_handle = curl_init("http://cl-api.vize.ai/{your task ID}");    //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 {your JWT token}",  //#use your JWT
    "cache-control: no-cache",));

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

Java

Use Java integration to classify the image. Use POST method with parameter "image" to http://cl-api.vize.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

Java code example:
HttpResponse response = Unirest.post("http://cl-api.vize.ai/{your task ID}")
.header("Authorization", "JWT {your JWT token}")
.field("image", new File("{myimage.jpg}"))
.asString();

Node.js

Use Node.js integration to classify the image. Use POST method with parameter "image" to http://cl-api.vize.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

Node.js code example:
unirest.post("http://cl-api.vize.ai/{your task ID}")
.header("Authorization", "JWT {your JWT token}")
.attach("image", fs.createReadStream("{myimage.jpg}"))
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

Objective-C

Use Objective-C integration to classify the image. Use POST method with parameter "image" to http://cl-api.vize.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

Objective-C code example:
NSURL *urlimage = [NSURL URLWithString:@"{myimage.jpg}"]
NSDictionary *headers = @{@"Authorization": @"JWT {your JWT token}"};
NSDictionary *parameters = @{@"image": urlimage};
UNIUrlConnection *asyncConnection = [[UNIRest post:^(UNISimpleRequest *request) {
  [request setUrl:@"http://cl-api.vize.ai/{your task ID}"];
  [request setHeaders:headers];
  [request setParameters:parameters];
}] asundefinedAsync:^(UNIHTTPundefinedResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];

.NET

Use .NET integration to classify the image. Use POST method with parameter "image" to http://cl-api.vize.ai/{your task ID}. To authenticate yourself use a JWT token given after training.

.NET code example:
Task> response = Unirest.post("http://cl-api.vize.ai/{your task ID}")
.header("Authorization", "JWT {your JWT token}")
.field("image", File.ReadAllBytes(@"{myimage.jpg}"))
.asString();

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": "prediction",
    "preprocess_time": 0.030581951141357422,
    "scores": {
        "category 1": 0.7789751887321472,
        "category 2": 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

Supported images are *.jpg, *.jpeg and *.png. Maximum size of an image is 3MB.

{
  "message": "invalid image type or size"
}
{
  "message": "Missing image or url"
}
{
  "message": "error downloading image from URL"
}
429 TOO MANY REQUESTS - Returns JSON formatted string
{
  "message": "limit rate exceeded"
}

Support

Please, feel free to contact us in case you need any help. Contact us at support@vize.ai

Get started for free now

Free, easy to set up, no credit card required