Docs & API reference

Getting started

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 practices

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

After you train your task in the app you are ready to deploy your private API endpoint.

Deploying API

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.

Classifier API

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.

Code snippets

curl -v -XPOST -H 'Authorization: JWT {your JWT Token}' -F 'image=@{path/mypicture.jpg};type=image/jpeg' http://cl-api.vize.ai/{task.id}import requests

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

headers = {"Authorization": "JWT {your JWT token}"}

response = requests.request("POST", url, files=files, headers=headers)
print(response.text)$file_name_with_full_path = realpath('{path/myimage.png}');
$curl_handle = curl_init("http://cl-api.vize.ai/{your task ID}");

curl_setopt($curl_handle, CURLOPT_POST, 1);
$args['image'] = new CurlFile({path/myimage.png}, '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}",
    "cache-control: no-cache",));

$returned_data = curl_exec($curl_handle);
curl_close ($curl_handle);
echo $returned_data;// Use http://unirest.io/nodejs open-source library.

unirest.post("http://cl-api.vize.ai/{your task ID}?image={path/myimage.png}")
.header("Authorization", "JWT {your JWT token}")
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "text/plain")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});// Use http://unirest.io/java open-source library.

HttpResponse response = Unirest.post("http://cl-api.vize.ai/{your task ID}?image={path/myimage.png}")
.header("Authorization", "JWT {your JWT token}")
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "text/plain")
.asString();// Use http://unirest.io/objective-c open-source library.

NSDictionary *headers = @{@"Authorization": @"JWT {your JWT token}", @"Content-Type": @"application/x-www-form-urlencoded", @"Accept": @"text/plain"};
UNIUrlConnection *asyncConnection = [[UNIRest post:^(UNISimpleRequest *request) {
  [request setUrl:@"http://cl-api.vize.ai/{your task ID}?image={path/myimage.png}"];
  [request setHeaders:headers];
}] asundefinedAsync:^(UNIHTTPundefinedResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];// Use http://unirest.io/net open-source library.

Task> response = Unirest.post("http://cl-api.vize.ai/{your task ID}?image={path/myimage.png}")
.header("Authorization", "JWT {your JWT token}")
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "text/plain")
.asString();# Use http://unirest.io/ruby open-source library.

response = Unirest.post "http://cl-api.vize.ai/{your task ID}?image={path/myimage.png}",
  headers:{
    "Authorization" => "JWT {your JWT token}",
    "Content-Type" => "application/x-www-form-urlencoded",
    "Accept" => "text/plain"
  }

JSON responses

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

Response Value
200 OK Returns JSON formatted string
400 BAD REQUEST Returns JSON formatted string
429 TOO MANY REQUESTS Returns HTML formatted string

200 - ok

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

{
  "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
  }
}

400 - bad request

Missing image.

{
  "message": "Missing image"
}

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

{
  "message": "invalid image type or size"
}

429 - too many requests

{
"message": "limit rate exceeded"
}
Get started freeContact us

Free, easy to set up, no credit card required