Curl Node Java Python

Visual Recognition

API Reference

Introduction

Similarity Search and collections closed: As of September 8, 2017, the beta period for Similarity Search is closed. For more information, see Visual Recognition API – Similarity Search Update.

The IBM Watson™ Visual Recognition service identifies scenes, objects, and celebrity faces in images you upload to the service. You can create and train a custom classifier to identify subjects that suit your needs.

Descriptions of Node classes referred to in this reference are available in the Node documentation for the Watson Developer Cloud Node.js SDK.

Descriptions of Java classes referred to in this reference are available in the Javadoc for the Watson Developer Cloud Java SDK.

Descriptions of Python classes referred to in this reference are available in the Python documentation for the Watson Developer Cloud Python SDK.

API endpoint

https://gateway-a.watsonplatform.net/visual-recognition/api

Important: If you have Bluemix Dedicated, this might not be your service endpoint. Double check your endpoint URL on the Service credentials page in your instance of the Visual Recognition Service on Bluemix.

npm

npm install watson-developer-cloud --save

pip

pip install --upgrade watson-developer-cloud

API explorer

You can also interact with the methods in the API explorer. To get familiar with the API, use the explorer to test your calls to the API and view live responses from the server.

Authentication

You authenticate to the Visual Recognition API by providing the API key that is provided in the service credentials for the service instance that you want to use.

After you create an instance of the Visual Recognition service, you can view the API key by selecting Service credentials from the service dashboard.

Replace {api-key} with your API key.

var watson = require('watson-developer-cloud');
var visual_recognition = watson.visual_recognition({
  api_key: '{api-key}',
  version_date: '2016-05-20'
});
		VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

import line to: from /usr/local/lib/python2.7/dist-packages/watson_developer_cloud import VisualRecognitionV3 as VisualRecognition

visual_recognition = VisualRecognition(
    api_key='{api-key}')

Classify

Classify an image

Classify a URL, or upload a single image or a .zip file of multiple images with the built-in classes. To identify custom classifiers, include the classifier_ids or owners parameters.classifierIDs parameter.

GET /v3/classify
POST /v3/classify
ServiceCall<VisualClassification> classify(ClassifyImagesOptions options)

GET Request

Use the GET method to classify URLs against classifiers as a query parameter.

Name Description
Accept-Language header string

The 2-letter primary language code as assigned in ISO standard 639. Supported languages are en (English), ar (Arabic), de (German), es (Spanish), it (Italian), ja (Japanese), and ko (Korean).

The response might not be in the specified language in these conditions:

  • English is returned when the requested language is not supported (see the parameter description for details).
  • Classes are not returned when there is no translation for them.
  • Custom classifiers returned with this method return tags in the language of the custom classifier.
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
url query string

The URL of an image (.jpg, .png). The minimum recommended pixel density is 32X32 pixels per inch, and the maximum image size is 2 MB.

Redirects are followed, so you can use a shortened URL. The resolved URL is returned in the response.

owners query string[, string...] A comma-separated list with the values IBM, me, or both to specify which classifiers to run.
classifier_ids query string[, string...] A comma-separated list of the classifier IDs used to classify the images. "default" is the classifier_id of the built-in classifier. A specialty "food" classifier is also available, to enhance specificity and accuracy for images of food items.
threshold query number A floating value that specifies the minimum score a class must have to be displayed in the response. The default threshold for returning scores from a classifier is 0.5. Set the threshold to 0.0 to ignore the classification score and return all values.

Example GET request

https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classify?api_key={api-key}&url=https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/fruitbowl.jpg&version=2016-05-20

To try out the API quickly, paste the GET request into your browser. Replace {api-key} fwith your API key from Bluemix.

POST Request

Use the POST method to upload a single image, URL, or a compressed (.zip) file of multiple images. You can analyze images against the built-in classifiers or against an array of classifier IDs.

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
Accept-Language header string

The 2-letter primary language code as assigned in ISO standard 639. Supported languages are en (English), ar (Arabic), de (German), es (Spanish), it (Italian), ja (Japanese), and ko (Korean).

The response might not be in the specified language in these conditions:

  • English is returned when the requested language is not supported (see the parameter description for details).
  • Classes are not returned when there is no translation for them.
  • Custom classifiers returned with this method return tags in the language of the custom classifier.
images_file form data file An image file (.jpg, .png) or .zip file of images. Maximum image size is 2 MB. Maximum .zip file size is 5 MB with up to 20 images. You can also include images with the url property in the parameters object.
parameters form data file A JSON parameters object that specifies additional request options.
parameters
Name Description
url string A string with the image URL to analyze. must be in .jpg, or .png format. The maximum image size is 2 MB. You can also include images in the images_file parameter.
classifier_ids string[ ] An array of classifier IDs to classify the images against.
owners string[ ] An array of the values IBM, me, or both to specify which classifiers to run.
threshold number A floating point value that specifies the minimum score a class must have to be returned in the response. The default value for returning scores is 0.5.

Example POST request

curl -X POST -F "images_file=@fruitbowl.jpg" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classify?api_key={api-key}&version=2016-05-20"

Example POST request with a parameters JSON

curl -X POST -F "images_file=@fruitbowl.jpg" -F "parameters=@fruit.json" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classify?api_key={api-key}&version=2016-05-20"

Example parameters file

{
   "classifier_ids":[
      "fruits_1462128776",
      "SatelliteModel_6242312846"
   ],
   "threshold":0.6
}
Parameter Type Description
api_key query (Required) Your API key.
version query (Required) The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
images_file multipart/form-data (Required) The image file (.jpg, or .png) or compressed (.zip) file of images to classify. The max number of images in a .zip file is limited to 20, and limited to 5 MB.
parameters multipart/form-data A JSON file containing input parameters. Input parameters can include:
  • url - A string with the image URL to analyze.
  • classifier_ids - An array of classifier IDs to classify the images against.
  • owners - An array with the value(s) "IBM" and/or "me" to specify which classifiers to run.
  • threshold - A floating point value that specifies the minimum score a class must have to be returned in the response.
Accept-Language Header The 2-letter primary language code as assigned in ISO standard 639. Supported languages are en (English), ar (Arabic), de (German), es (Spanish), it (Italian), ja (Japanese), and ko (Korean).

Example request

var watson = require('watson-developer-cloud');
var fs = require('fs');

var visual_recognition = watson.visual_recognition({
  api_key: '{api_key}',
  version: 'v3',
  version_date: '2016-05-20'
});

var params = {
  images_file: fs.createReadStream('./resources/car.png')
};

visual_recognition.classify(params, function(err, res) {
  if (err)
    console.log(err);
  else
    console.log(JSON.stringify(res, null, 2));
});
Name Description
Accept-Language header string

The 2-letter primary language code as assigned in ISO standard 639. Supported languages are en (English), ar (Arabic), de (German), es (Spanish), it (Italian), ja (Japanese), and ko (Korean).

The response might not be in the specified language in these conditions:

  • English is returned when the requested language is not supported (see the parameter description for details).
  • Classes are not returned when there is no translation for them.
  • Custom classifiers returned with this method return tags in the language of the custom classifier.
options object A Java classifyImagesOptions object that specifies the parameters of the request. To create an instance of the object, use the ClassifyImagesOptions.Builder static nested class.
Java ClassifyImagesOptions
Name Description
classifierIds string or List<String>

A single classifier ID or an list of IDs to classify the images against.

Add the classifiers either by specifying a single string classifierID or by specifying a list of string classifierIds in a call to the .classifierIds method of the ClassifyImagesOptions.Builder class.

images byte[ ] and string or File

The image or .zip file of images to classify. Images must be in .jpg, or .png format. The maximum image size is 2 MB. The maximum .zip file size is 100 MB with up to 10,000 images. You can also include images with the url method.

Add the images either by specifying a single imageName string and imagesBinary image file or by specifying an imagesFile .zip file in a call to the .images method of the ClassifyImagesOptions.Builder class.

threshold Double A floating point value that specifies the minimum score a class must have to be returned in the response. The default threshold for returning scores from a classifier is 0.5.
url string The image URL to analyze.
Constructor: ClassifyImagesOptions.Builder

Example request

VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

ClassifyImagesOptions options = new ClassifyImagesOptions.Builder()
    .images(new File("./subway.jpg"))
    .build();
VisualClassification result = service.classify(options).execute();
System.out.println(result);
Parameter Type Description
api_key query (Required) Your API key.
version query (Required) The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
images_file multipart/form-data (Required) The image file (.jpg, or .png) or compressed (.zip) file of images to classify. The max number of images in a .zip file is limited to 20, and limited to 5 MB.
parameters multipart/form-data A JSON file containing input parameters. Input parameters can include:
  • url - A string with the image URL to analyze.
  • classifier_ids - An array of classifier IDs to classify the images against.
  • owners - An array with the value(s) "IBM" and/or "me" to specify which classifiers to run.
  • threshold - A floating point value that specifies the minimum score a class must have to be returned in the response.
Accept-Language Header The 2-letter primary language code as assigned in ISO standard 639. Supported languages are en (English), ar (Arabic), de (German), es (Spanish), it (Italian), ja (Japanese), and ko (Korean).

Example request

import json
from os.path import join, dirname
from os import environ
from watson_developer_cloud import VisualRecognitionV3

visual_recognition = VisualRecognitionV3('2016-05-20', api_key='{api-key}')

print(json.dumps(visual_recognition.classify(images_url=https://www.ibm.com/ibm/ginni/images/ginni_bio_780x981_v4_03162016.jpg), indent=2))

Response

ClassifiedImages (Java VisualClassification object)
Name Description
custom_classes integer The number of custom classes identified in the images.
images_processed integer The number of images processed.
images object[ ] An array of ClassifiedImage objects that describes the classified images.
warnings object[ ] An array of WarningInfo objects that provides information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.
ClassifiedImage
Parameter Description
classifiers object[ ] An array of ClassifierResult objects that describes the classified images.
image string The relative path of the image file. Not returned when the image is passed by URL.
source_url string The source of the image before any redirects. Not returned when the image is uploaded.
resolved_url string The fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded.
errors object An ErrorInfo object that provides information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.
ClassifierResult
Parameter Description
classes object[ ] An array of ClassResult objects for the classifier that provides information about the classes identified in the image.
classifier_id string The ID of a classifier identified in the image.
name string The name of the classifier identified in the image.
ClassResult
Parameter Description
class string The name of the class identified in the image.
score double The score of a class identified in the image in the range of 0 to 1. A higher score indicates greater likelihood that the class is depicted in the image. The default threshold for returning scores from a classifier is 0.5.
type_hierarchy string Type hierarchy. For example, People/Leaders/Presidents/USA/Barack Obama. Included only included if identified.
WarningInfo
Parameter Description
warning_id string A codified string ID for a specific warning.
description string Information about the warning.
ErrorInfo
Parameter Description
error_id string A codified string ID for a specific error.
description string Information about the error.

Example response

{
  "custom_classes": 0,
  "images": [{
    "classifiers": [{
      "classes": [{
          "class": "banana",
          "score": 0.562,
          "type_hierarchy": "/fruit/banana"
        },
        {
          "class": "fruit",
          "score": 0.788
        },
        {
          "class": "diet (food)",
          "score": 0.528,
          "type_hierarchy": "/food/diet (food)"
        },
        {
          "class": "food",
          "score": 0.528
        },
        {
          "class": "honeydew",
          "score": 0.5,
          "type_hierarchy": "/fruit/melon/honeydew"
        },
        {
          "class": "melon",
          "score": 0.501
        },
        {
          "class": "olive color",
          "score": 0.973
        },
        {
          "class": "lemon yellow color",
          "score": 0.789
        }
      ],
      "classifier_id": "default",
      "name": "default"
    }],
    "image": "fruitbowl.jpg"
  }],
  "images_processed": 1
}

Detect faces

Analyze faces in images and get data about them, such as estimated age, gender, plus names of celebrities. Images can be in .jpg, or .png format. This feature is not trainable, and does not support general biometric facial recognition.

For each image, the response includes face location, a minimum and maximum estimated age, a gender, and confidence scores. Scores range from 0 - 1 with a higher score indicating greater correlation.

GET /v3/detect_faces
POST /v3/detect_faces
ServiceCall<DetectedFaces> detectFaces(VisualRecognitionOptions options)

GET Request

Use the GET method to detect faces in a single URL.

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
url query string

The URL of an image (.jpg, .png). The maximum image size is 2 MB. The service detects all faces in the image, but if more than 10 faces exist in an image, age and gender confidence scores might return scores of 0.

If there are more than 10 faces in an image, all the faces are detected, but age and gender confidence might return scores of 0.

Example GET request

https://gateway-a.watsonplatform.net/visual-recognition/api/v3/detect_faces?api_key={api_key}&url=https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/prez.jpg&version=2016-05-20

To try out the API quickly, paste the GET request into your browser. Replace {api-key} with your API key from Bluemix.

POST Request

Use the POST method to upload a single image, URL, or a compressed (.zip) file of multiple images.

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
images_file form data file

An image file (.jpg, .png) or .zip file with images. Include no more than 15 images. The maximum image size is 2 MB. The maximum .zip file size is 5 MB. You can also include images with the url property in the parameters object.

If there are more than 10 faces in an image, all the faces are detected, but age and gender confidence might return scores of 0.

parameters form data file A JSON parameters object that specifies additional request options.

Example POST request

curl -X POST -F "images_file=@prez.jpg" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/detect_faces?api_key={api-key}&version=2016-05-20"

Example parameters JSON file


{
    "url": "https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/prez.jpg"
}
Parameter Type Description
api_key query (Required) Your API key.
version query (Required) The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
images_file multipart/form-data The image file (.jpg, .png) or compressed (.zip) file of images to analyze. The total number of images is limited to 15. All faces are detected, but if there are more than 10 faces in an image, age and gender confidence scores might return scores of 0.
parameters multipart/form-data A JSON file containing a string of a single URL to analyze.

Example request

var watson = require('watson-developer-cloud');
var fs = require('fs');
var visual_recognition = watson.visual_recognition({
  api_key: '{api_key}',
  version: 'v3',
  version_date: '2016-05-20'
});

var params = {
  images_file: fs.createReadStream('./resources/obama.jpg')
};

visual_recognition.detectFaces(params,
  function(err, response) {
    if (err)
      console.log(err);
    else
      console.log(JSON.stringify(response, null, 2));
  });
Name Description
images string or File

An image file (.jpg, .png) or .zip file with images. Include no more than 15 images. The maximum image size is 2 MB. The maximum .zip file size is 5 MB. You can also include images with the url parameter.

All faces are detected, but if there are more than 10 faces in an image, age and gender confidence scores may return scores of 0.

url string The image URL to analyze.

Example request

VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

VisualRecognitionOptions options = new VisualRecognitionOptions.Builder()
    .images(new File("./prez.jpg"))
    .build();
DetectedFaces result = service.detectFaces(options).execute();
System.out.println(result);
Parameter Type Description
api_key query (Required) Your API key.
version query (Required) The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
images_file multipart/form-data (Required) The image file (.jpg, or .png) or compressed (.zip) file of images to analyze. The total number of images is limited to 15.All faces are detected, but if there are greater than 10 faces in an image, age and gender confidence scores might return scores of 0.
parameters multipart/form-data A JSON file containing a string of a single URL to analyze.

Example request

import json
from os.path import join, dirname
from os import environ
from watson_developer_cloud import VisualRecognitionV3

visual_recognition = VisualRecognitionV3('2016-05-20', api_key='{api_key}')

print(json.dumps(visual_recognition.detect_faces(images_url=https://www.ibm.com/ibm/ginni/images/ginni_bio_780x981_v4_03162016.jpg), indent=2))

Response

Name Description
images The array of images.
faces An array of the faces detected in the images.
age An array of age information about a detected face. If there are greater than 10 faces in an image, age confidence scores might return a score of 0.
max The maximum estimated age for a detected face.
min The minimum estimated age for a detected face.
face_location An array of information that defines the location of bounding box around a detected face.
height Vertical distance in pixels from one edge of the bounding box around a face to the other.
left X-position of the top-left pixel of the face bounding box.
top Y-position of the top-left pixel of the face bounding box.
width Horizontal distance in pixels from one edge of the bounding box around a face to the other.
gender An array of information containing the gender of the detected face. For example, "MALE" or "FEMALE". If there are greater than 10 faces in an image, gender confidence scores might return a score of 0.
identity The identity of a celebrity detected in the image. If no celebrity is detected, the parameter returns empty.
name The name of the detected celebrity.
type_hierarchy A knowledge graph of the celebrity identity. Only return if a type hierarchy is found.
score The confidence score of the ages, gender, or celebrity indentity identified for a detected face.
image The relative path of the image file. Omitted if the image is passed by URL.
source_url The source URL of the image, before any redirects. Omitted if the image is uploaded.
resolved_url The fully-resolved URL of the image, after redirects are followed. Omitted if the image is uploaded.
images_processed The number of images processed by the API call.
error An object containing information about what might have caused a failure, such as an image that is too large. Omitted if there are no errors.
error_id A codified string ID for a specific error. For example, "limit_exceeded".
description A human-readable error description. For example, "File size limit (1MB) exceeded".
warnings An array containing informaton about what might cause the output to be less than optimal. For example, a call with a corrupt .zip file and a list of image URLs will still complete but will not have the expected output. Omitted if there are no warnings.

Example response

{
  "images": [{
    "faces": [{
      "age": {
        "max": 44,
        "min": 35,
        "score": 0.446989
      },
      "face_location": {
        "height": 159,
        "left": 256,
        "top": 64,
        "width": 92
      },
      "gender": {
        "gender": "MALE",
        "score": 0.99593
      },
      "identity": {
        "name": "Barack Obama",
        "score": 0.970688,
        "type_hierarchy": "/people/politicians/democrats/barack obama"
      }
    }],
    "image": "prez.jpg"
  }],
  "images_processed": 1
}

Custom classifiers

Create a classifier

Train a new multi-faceted classifier on the uploaded image data. Create your custom classifier with positive or negative examples. Include at least two sets of examples, either two positive example files or one positive and one negative file. You can upload a maximum of 256 MB per call.

For details, see Structure of the training data, and Guidelines for good training.

POST /v3/classifiers
ServiceCall<VisualClassifier> createClassifier(ClassifierOptions options)

Request

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
{class}_positive_examples form data file

A .zip file of images that depict the visual subject of a class in the new classifier. You can include more than one positive example file in a call. Append _positive_examples to the form name. The prefix is used as the class name. For example, goldenretriever_positive_examples creates the class goldenretriever.

Include at least 10 images in .jpg or .png format. The minimum recommended image resolution is 32X32 pixels. The maximum image size is 2 MB. The maximum number of images is 10,000 images or 100 MB per .zip file

negative_examples form data file

A .zip file of images that do not depict the visual subject of any classes in the classifier. The negative examples do not create a class, but define what the updated classifier is not. You can specify only one negative example file in a call. Include at least 10 images in .jpg or .png format.

name form data string The name of the new classifier. Cannot contain special characters.
Name Description
options object A Java ClassifierOptions object that specifies the parameters of the request. To create an instance of the object, use the ClassifierOptions.Builder static nested class.
Java ClassifierOptions
Name Description
classifierName string The name of the new classifier. Cannot contain special characters.
positiveExamplesByName object

A class name and .zip file of images that depict the visual subject of the class within the new classifier. You can include more than one positive example file in a call.

Include at least 10 images in .jpg or .png format. The minimum recommended image resolution is 32X32 pixels. The maximum image size is 2 MB. The maximum number of images is 10,000 images or 100 MB per .zip file

Add the positive examples class by specifying the className string and the positiveExamples .zip file in a call to the addClass method of the ClassifierOptions.Builder class.

negativeExamples File

A .zip file of images that do not depict the visual subject of any classes in the classifier. The negative examples do not create a class, but define what the updated classifier is not. You can specify only one negative example file in a call. Include at least 10 images in .jpg or .png format.

Add examples by specifying the .zip file in a call to the .negativeExamples method of the ClassifierOptions.Builder class.

Constructor: ClassifierOptions.Builder

Example request

curl -X POST -F "beagle_positive_examples=@beagle.zip" -F "goldenretriever_positive_examples=@golden-retriever.zip" -F "husky_positive_example=@husky.zip" -F "negative_examples=@cats.zip" -F "name=dogs" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers?api_key={api-key}&version=2016-05-20"
var watson = require('watson-developer-cloud');
var fs = require('fs');

var visual_recognition = watson.visual_recognition({
  api_key: '{api_key}',
  version: 'v3',
  version_date: '2016-05-20'
});

var params = {
  name: 'fruit',
  apple_positive_examples: fs.createReadStream('./apples.zip'),
    banana_positive_examples: fs.createReadStream('./yellow.zip'),
    orange_positive_examples: fs.createReadStream('./pos_ex.zip'),
  negative_examples: fs.createReadStream('./vegetables.zip')
};

visual_recognition.createClassifier(params,
  function(err, response) {
   	 if (err)
      		console.log(err);
    	 else
   		console.log(JSON.stringify(response, null, 2));
});
VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

Builder options = new ClassifierOptions.Builder()
    .classifierName("dogs")
    .addClass("beagle", new File("./beagle.zip"))
    .addClass("goldenretriever",new File("./golden-retriever.zip"))
    .addClass("husky", new File("./husky.zip"))
    .negativeExamples(new File("./cats.zip"));

VisualClassifier dogs = service.createClassifier(options.build()).execute();
System.out.println(dogs);
with open(join(dirname(__file__), '../resources/trucks.zip'), 'rb') as trucks, \
      open(join(dirname(__file__), '../resources/cars.zip'), 'rb') as cars:
   print(json.dumps(visual_recognition.create_classifier('CarsvsTrucks', trucks_positive_examples=trucks, negative_examples=cars), indent=2))

Depending on the size of the training files, this call can take several minutes to complete.

Response

Classifier (Java VisualClassifier object)
Name Description
classifier_id The ID of the new classifier.
name The name of the new classifier.
owner Unique ID of the account that owns the classifier.
status The training status of the classifier of type VisualClassifier.status. Valid values are ready, failed, or training
created Date and time in Coordinated Universal Time that the classifier was created.
classes An array of class names that define the classifier.
Class (Java VisualClassifier.VisualClass object)
Name Description
class The name of the class.

Example response

{
    "classifier_id": "dogs_1477088859",
    "name": "dogs",
    "owner": "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
    "status": "training",
    "created": "2017-09-12T14:34:22.965",
    "classes": [
        {"class": "goldenretriever"},
        {"class": "beagle"},
        {"class": "husky"}
    ]
}

Retrieve a list of custom classifiers

Retrieve a list of user-created classifiers.

GET /v3/classifiers
ServiceCall<List<VisualClassifier>> getClassifiers()

Request

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
verbose query boolean Specify true to return classifier details. Omit this parameter to return a simple list of classifiers.

No arguments.

Example request

curl -X GET "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers?api_key={api-key}&version=2016-05-20"
var watson = require('watson-developer-cloud');

var visual_recognition = watson.visual_recognition({
  api_key: '{api_key}',
  version: 'v3',
  version_date: '2016-05-20'
});

visual_recognition.listClassifiers({},
  function(err, response) {
   if (err)
    console.log(err);
   else
    console.log(JSON.stringify(response, null, 2));
  }
);
VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

List<VisualClassifier> classifiers = service.getClassifiers().execute();
System.out.println(classifiers);
print(json.dumps(visual_recognition.list_classifiers(), indent=2))

Response

Classifiers
Name Description
classifiers An array of Classifier A list of VisualClassifer objects that are available for the service instance.
Classifier (Java VisualClassifier object)
Name Description
created Date and time in Coordinated Universal Time that the classifier was created.
classifier_id The ID of the classifier.
name The name of the classifier.
status The training status of the classifier of type VisualClassifier.status. Valid values are ready, failed, training, or retraining
owner Unique ID of the account who owns the classifier. Returned only when verbose=true.
classes An array of class names that define the classifier.
Class (Java VisualClassifier.VisualClass object)
Name Description
class The name of the class.

Example response

{
  "classifiers": [
    {
      "classifier_id": "dogs_1477088859",
      "name": "dogs",
      "status": "ready"
    },
    {
      "classifier_id": "CarsvsTrucks_1479118188",
      "name": "Cars vs Trucks",
      "status": "ready"
    }
  ]
}
[
  {
    "classes": [
      {
        "class": "cars"
      }
    ],
    "created": "2016-07-19T11:24:08.743",
    "classifier_id": "CarsvsTrucks_1479118188",
    "name": "Cars vs Trucks",
    "owner": "99d0114d-9959-4071-b06f-654701909be4",
    "status": "ready"
  },
  {
    "classes": [
      {
        "class": "goldenretriever"
      },
      {
        "class": "beagle"
      },
      {
        "class": "husky"
      }
    ],
    "created": "2017-09-12T14: 34: 22.965",
    "classifier_id": "dogs_1477088859",
    "name": "dogs",
    "owner": "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
    "status": "ready"
  }
]

Retrieve classifier details

Retrieve information about a specific classifier.

GET /v3/classifiers/{classifier_id}
ServiceCall<VisualClassifier> getClassifier(String classifierId)

Request

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
classifier_id query string The unique identifier for a classifier. To see a list of classifiers, use the GET /v3/classifiers method.
Name Description
classifierId string The unique identifier for a classifier. To see a list of classifiers, use the getClassifiers method.

Example request

curl -X GET
"https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859?api_key={api-key}&version=2016-05-20" 
var watson = require('watson-developer-cloud');

var visual_recognition = watson.visual_recognition({
  api_key: '{api_key}',
  version: 'v3',
  version_date: '2016-05-20'
});

visual_recognition.getClassifier({
  classifier_id: 'dogs_1477088859' },
  function(err, response) {
   if (err)
    console.log(err);
   else
    console.log(JSON.stringify(response, null, 2));
  }
);
VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

VisualClassifier classifier = service.getClassifier("dogs_1477088859").execute();
System.out.println(classifier);
print(json.dumps(visual_recognition.get_classifier('dogs_1477088859'), indent=2))

Response

Classifier (Java VisualClassifier object)
Name Description
classifier_id The ID of the specified classifier.
name The name of the specified classifier.
owner The ID of the account that owns the classifier.
status The training status of the classifier of type VisualClassifier.status. Valid values are ready, failed, training, or retraining
created Date and time in Coordinated Universal Time that the classifier was created.
classes An array of class names that define the classifier.
Class (Java VisualClassifier.VisualClass object)
Name Description
class The name of the class.

Example response

{
  "classifier_id": "dogs_1477088859",
  "name": "dogs",
  "owner": "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
  "status": "training",
  "created": "2017-09-12T14:34:22.965",
  "classes": [
    {"class": "goldenretriever"},
    {"class": "beagle"},
    {"class": "husky"}
  ]
}

Update a classifier

Update a custom classifier by adding new positive or negative classes (examples) or by adding new images to existing classes. You must supply at least one set of positive or negative examples.

Important: You can't update a custom classifier with a free API key. If you have a free key, you can upgrade to a Standard plan. For details, see Changing your plan.

Tip: Don't make additional retraining calls on the same classifier until the status is ready. When you submit retraining requests in parallel, the last request overwrites the previous requests. The retrained property shows the last time the classifier retraining finished.

For details, see Updating custom classifiers.

POST /v3/classifiers/{classifier_id}
ServiceCall<VisualClassifier> updateClassifier(String classifierId, ClassifierOptions options)

Request

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
classifier_id query string The ID of the classifier that you want to update. To see a list of classifiers, use the GET /v3/classifiers method.
{class}_positive_examples form data file

A .zip file of images that depict the visual subject of a class in the classifier. The positive examples create or update classes in the classifier. You can include more than one positive example file in a call. Append _positive_examples to the form name. The prefix is used to name the class. For example, goldenretriever_positive_examples creates the class goldenretriever.

The file must contain a minimum of 10 images in .jpg or .png format. Minimum recommended size is 32X32 pixels. The maximum image size is 2 MB. The maximum number of images is 20 and file size is 5 MB.

negative_examples form data file

A .zip file of images that do not depict the visual subject of any classes in the classifier or any of the positive examples. The negative examples do not create a class, but define what the updated classifier is not. You can specify only one negative example file in a call. Include at least 10 images in .jpg or .png format.

Name Description
classifierId string The ID of the classifier that you want to update. To see a list of classifiers, use the getClassifiers method.
options object A Java ClassifierOptions object that specifies the parameters of the request. To create an instance of the object, use the ClassifierOptions.Builder static nested class.
Java ClassifierOptions
Name Description
positiveExamplesByName object

A class name and .zip file of images that depict the visual subject of the class within the new classifier. You can include more than one positive example file in a call.

Include at least 10 images in .jpg or .png format. The minimum recommended image resolution is 32X32 pixels. The maximum image size is 2 MB. The maximum .zip file size is 5 MB.

Add the positive examples class by specifying the className string and the positiveExamples .zip file in a call to the addClass method of the ClassifierOptions.Builder class.

negativeExamples File

A .zip file of images that do not depict the visual subject of any classes in the classifier or any of the positive examples. The negative examples do not create a class, but define what the updated classifier is not. You can specify only one negative example file in a call. Include at least 10 images in .jpg or .png format.

Add examples by specifying the .zip file in a call to the .negativeExamples method of the ClassifierOptions.Builder class.

Constructor: ClassifierOptions.Builder

Example request

curl -X POST -F "dalmatian_positive_examples=@dalmatian.zip" -F "negative_examples=@more-cats.zip" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859?api_key={api-key}&version=2016-05-20" 

The size of the training files affects the response time, which can take several minutes.

Node.js example coming soon.
VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key");
String classifierId = "dogs_1477088859";

Builder options = new ClassifierOptions.Builder()
    .addClass("dalmatian", new File("./dalmatian.zip"))
    .negativeExamples(new File("./more-cats.zip"));

VisualClassifier updatedDogs = service.updateClassifier(classifierId, options.build()).execute();
System.out.println(updatedDogs);
Python example coming soon.

Response

Name Description
classifier_id The ID of the new classifier.
name The name of the new classifier.
owner Unique ID of the account who owns the classifier.
status The training status of the classifier. Valid values are ready, failed, training, or retraining
explanation Omitted if the classifier trains successfully. If the classifier training fails, this might explain why training failed.
created Date and time in Coordinated Universal Time that the classifier was created.
classes An array of classes that define a classifier.
retrained Date and time in Coordinated Universal Time that the classifier was updated.
class The name of the class.

Example response

{
  "classifier_id": "dogs_1477088859",
  "name": "dogs",
  "owner": "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
  "status": "ready",
  "created": "2017-09-12T14:34:22.965",
  "classes": [
    {"class": "goldenretriever"},
    {"class": "beagle"},
    {"class": "husky"},
    {"class": "dalmatian"}
  ],
  "retrained": "2017-09-15T15:52:03.832Z"
}

Delete a classifier

Delete a custom classifier with the specified classifier ID.

DELETE /v3/classifiers/{classifier_id}
ServiceCall<Void> deleteClassifier(String classifierId)

Request

Name Description
api_key query string Your API key.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2016-05-20.
classifier_id query string The identifier of the classifier that you want to delete.
Name Description
classifierId string The identifier of the classifier that you want to delete.

Example request

curl -X DELETE
"https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859?api_key={api-key}&version=2016-05-20"

var watson = require('watson-developer-cloud');

var visual_recognition = watson.visual_recognition({
  api_key: '{api_key}',
  version: 'v3',
  version_date: '2016-05-20'
});

visual_recognition.deleteClassifier({
  classifier_id: 'dogs_1477088859' },
  function(err, response) {
   if (err)
    console.log(err);
   else
    console.log(JSON.stringify(response, null, 2));
  }
);
VisualRecognition service = new VisualRecognition(VisualRecognition
    .VERSION_DATE_2016_05_20);
service.setApiKey("{api-key}");

service.deleteClassifier("dogs_1477088859").execute();
print(json.dumps(visual_recognition.delete_classifier(classifier_id='dogs_1477088859'), indent=2))

Response

No arguments

Example response

{ }

Data collection

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out header parameter to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access for general service improvements. set the X-Watson-Learning-Opt-Out header parameter to true when you create the service instance. (Any value other than false or 0 disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access for general service improvements. set the x-watson-learning-opt-out header parameter to true when you create the service instance. (Any value other than false or 0 disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access for general service improvements.

Error handling

The Visual Recognition service uses standard HTTP response codes to display whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Error information

Status Description
200 - Partial Success Problems with an individual image in an otherwise successfull request, for example, an image of invalid type
400 - Invalid Request Invalid request due to user input, for example:
  • Bad JSON input
  • Bad query parameter or header
  • Invalid output language
  • No input images
  • Corrupt .zip file
401 - Unauthorized No API key provided, or the API key provided was not valid.
404 - Not Found The requested item or parameter doesn't exist.
413 - Request Entity Too Large The size of the file in the request is larger than the maximum supported size.
500 - Internal Server Error Too many training requests or general server communication problems

Error format

Name Description
error An object containing information about the error.
code HTTP status code

Example error response

   {
      "error": "Too many images in collection",
      "code": 400
   }

Attributions

All images used on this page are from Flikr and used under Creative Commons Attribution 2.0 license . No changes were made to these images.