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<ClassifiedImages> classify(ClassifyOptions classifyOptions)

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 an image 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
}

Request

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 values IBM, me, or both 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));
});

Request

Pass the parameters as a Java ClassifyOptions object with the classifyOptions argument.

Name Description
acceptLanguage 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.
imagesFile object or File

The image or .zip file of images. 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 either stream the image file or .zip file, or you can specify a file on disk. You can also include an image in the url property of the parameters parameter.

imagesFileContentType string The audio format (MIME type) of the image files. The API detects the type from the filename, but you can specify the type if incorrect. Acceptable MIME type values are image/jpeg, image/png, and application/zip.
imagesFilename string The name of the image or .zip file
parameters string A JSON object that contains the 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 values IBM, me, or both 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.

Example request

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

InputStream imagesStream = new FileInputStream("./fruitbowl.jpg");
ClassifyOptions classifyOptions = new ClassifyOptions.Builder()
  .imagesFile(imagesStream)
  .imagesFilename("fruitbowl.jpg")
  .parameters("{\"classifier_ids\": [\"fruits_1462128776\","
    + "\"SatelliteModel_6242312846\"],"
    + "\"owners\": [\"IBM\", \"me\"]}")
  .build();
ClassifiedImages result = service.classify(classifyOptions).execute();
System.out.println(result);

Request

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 values IBM, me, or both 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 a response that might not include the expected output. For example, a request sent with more than 20 images in the .zip file, or a request with a corrupt .zip file and an image URL. 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.
error 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 number 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 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 and get data about faces in images. Responses can include estimated age and gender, and the service can identify celebrities. This feature uses a built-in classifier, so you do not train it on custom classifiers. The Detect faces method does not support general biometric facial recognition.

GET /v3/detect_faces
POST /v3/detect_faces
ServiceCall<DetectedFaces> detectFaces(DetectFacesOptions detectFacesOptions)

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. 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. Maximum image size is 2 MB. Maximum .zip file size is 5 MB with up to 15 images. You can also include an image 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.
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.

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

Request

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));
  });

Request

Pass the parameters as a Java DetectFacesOptions object with the detectFacesOptions argument.

Name Description
imagesFile object or File

The image or .zip file of images. 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. 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.

You can either stream the image file or .zip file, or you can specify a file on disk. You can also include an image in the url property of the parameters parameter.

imagesFileContentType string The audio format (MIME type) of the imagesFile. The API detects the type from the imagesFilename, but you can specify the type if incorrect. Acceptable MIME type values are image/jpeg, image/png, and application/zip.
imagesFilename string The name of the image or .zip file
parameters string A JSON object that contains the image URL to analyze ({\"url\":\"https://www.example.com/images/prez.jpg\"}. Must be in .jpg, or .png format. The maximum image size is 2 MB. You can also include images in the imagesFile parameter.

Example request

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

DetectFacesOptions detectFacesOptions = new DetectFacesOptions.Builder()
  .imagesFile(new File("./prez.jpg"))
  .build();
DetectedFaces result = service.detectFaces(detectFacesOptions).execute();
System.out.println(result);

Request

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

DetectedFaces (Java DetectedFaces object)
Name Description
images_processed integer The number of images processed.
images object[ ] An array of ImageWithFaces objects that describes the classified images.
warnings object[ ] An array of WarningInfo objects that provides information about a response that might not include the expected output. For example, a request sent with more than 15 images in the .zip file, or a request with a corrupt .zip file and an image URL. Not returned when there is no warning.
ImageWithFaces (Java ImageWithFaces object)
Parameter Description
faces object[ ] An array of Face objects that provides information about the faces detected in the image.
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.
error 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.
.
Face (Java Face object)
Parameter Description
age object An FaceAge object that provides age information about a face. If there are more than 10 faces in an image, the response might return the confidence score 0.
gender object A FaceGender object that provides information about the gender of the detected face. If there are more than 10 faces in an image, the response might return the confidence score 0.
face_location object A FaceLocation object that defines the location of the bounding box around the face.
identity object An FaceIdentity object that provides information about a celebrity who is detected in the image. Not returned when a celebrity is not detected.
FaceAge (Java FaceAge object)
Parameter Description
max integer Estimated maximum age.
min integer Estimated minimum age.
score number The confidence score for the ages in the range of 0 to 1.
FaceGender(Java FaceGender object)
Parameter Description
gender String The gender identified by the face. For example, MALE or FEMALE.
score number The confidence score for the gender in the range of 0 to 1.
FaceLocation (Java FaceFaceLocation object)
Parameter Description
height integer Height in pixels of the face region.
width integer Width in pixels of the face region.
left integer X-position of the top-left pixel of the face region.
top integer Y-position of the top-left pixel of the face region.
FaceIdentity (Java FaceIdentity object)
Parameter Description
name string The name of the person.
score number The confidence score for the identity of the celebrity in the range of 0 to 1.
type_hierarchy A knowledge graph of the celebrity. For example, People/Leaders/Presidents/USA/Barack Obama. Included only if identified.

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<Classifier> createClassifier(CreateClassifierOptions createClassifierOptions)

Request

Pass the parameters as a Java CreateClassifierOptions object with the createClassifierOptions argument.

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
name string The name of the new classifier. Cannot contain special characters.
positiveExamples 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 name of the classifier and the .zip file in a call to the addClass method of the CreateClassifierOptions.Builder class.

negativeExamples object or 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.

You can either stream the .zip file, or you can specify a file on disk.

negativeExamplesFilename string The name of the .zip file

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}");

CreateClassifierOptions createClassifierOptions = new CreateClassifierOptions.Builder()
  .name("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"))
  .build();

Classifier dogs = service.createClassifier(createClassifierOptions).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 Classifier 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 Classifier.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 Classifier 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<Classifiers> listClassifiers(ListClassifiersOptions listClassifiersOptions)

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.
verbose boolean Specify true to return classifier details. Omit this parameter to return a simple list of classifiers.

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}");

ListClassifiersOptions listClassifiersOptions = new ListClassifiersOptions.Builder()
  .verbose(true)
  .build();
Classifiers classifiers = service.listClassifiers(listClassifiersOptions).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 Classifier objects that are available for the service instance.
Classifier (Java Classifier 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 Classifier.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 Class 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<Classifier> getClassifier(GetClassifierOptions getClassifierOptions)

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 create an instance of the object, use the GetClassifierOptions.Builder static nested class. To see a list of classifiers, use the listClassifiers 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}");

GetClassifierOptions getClassifierOptions = new GetClassifierOptions.Builder("dogs_1477088859").build();
Classifier classifier = service.getClassifier(getClassifierOptions).execute();
System.out.println(classifier);
print(json.dumps(visual_recognition.get_classifier('dogs_1477088859'), indent=2))

Response

Classifier (Java Classifier 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 Classifier. 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 Class 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 retraining calls on a 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<Classifier> updateClassifier(UpdateClassifierOptions updateClassifierOptions)

Request

Pass the classifier ID with the method's classifierId argument. Pass all other parameters as a Java UpdateClassifierOptions object with the updateClassifierOptions argument.

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
positiveExamples object

A class name and .zip file of images that depict the visual subject of the class within the 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 name of the classifier and the .zip file in a call to the addClass method of the UpdateClassifierOptions.Builder class.

negativeExamples object or 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.

You can either stream the .zip file, or you can specify a file on disk.

negativeExamplesFilename string The name of the .zip file

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";

InputStream negativeExamples = new FileInputStream("./more-cats.zip");
UpdateClassifierOptions options = new UpdateClassifierOptions.Builder()
  .classifierId(classifierId)
  .addClass("dalmatian", new File("./dalmatian.zip"))
  .negativeExamples(negativeExamples)
  .negativeExamplesFilename("more-cats.zip")
  .build();

Classifier updatedDogs = service.updateClassifier(options).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(DeleteClassifierOptions deleteClassifierOptions)

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 object A DeleteClassifierOptions object that identifies 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}");

DeleteClassifierOptions options = new DeleteClassifierOptions.Builder("dogs_147708889").build();
service.deleteClassifier(options).execute();
print(json.dumps(visual_recognition.delete_classifier(classifier_id='dogs_1477088859'), indent=2))

Response

No response body

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 .zip 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.