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

API endpoint

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

Important: If you have IBM® Cloud Dedicated, this might not be your endpoint. Check your endpoint URL on the Service credentials page for your instance of the Visual Recognition service.

npm

npm install watson-developer-cloud --save

pip

pip install --upgrade "watson-developer-cloud>=1.0,<2.0"

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.

You can view the API key for a service instance from the Existing Services page of the Watson console. For more information, see Service credentials for Watson services.

You can also use tokens to make authenticated requests to Watson services without embedding service credentials in every call. You write an authentication proxy in IBM® Cloud to obtain a token for your client application, which can then use the token to call the service directly. You use your service credentials to obtain a token for that service. For more information, see Tokens for authentication.

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}");
from watson_developer_cloud import VisualRecognitionV3

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

General

Classify images

Classify images with the built-in or custom classifiers.

GET /v3/classify
POST /v3/classify
ServiceCall<ClassifiedImages> classify(ClassifyOptions classifyOptions)
classify(images_file=None, parameters=None, accept_language=None, images_file_content_type=None, images_filename=None)

GET Request

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 10 MB.

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

owners query string[, string...]

Specifies which categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty.

classifier_ids query string[, string...]

An array that specifies which classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The following built-in classifier_ids require no training:

  • default: Returns classes from thousands of general tags.
  • food: (Beta) Enhances specificity and accuracy for images of food items.
  • explicit: (Beta) Evaluates whether the image might be pornographic.

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} with your API key from IBM Cloud.

POST Request

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.
  • 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.
images_file form data file An image file (.jpg, .png) or .zip file of images. Maximum image size is 10 MB. Include no more than 20 images and limit the .zip file to 100 MB. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters. 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 minimum recommended pixel density is 32X32 pixels per inch, and the maximum image size is 10 MB. You can also include images in the images_file parameter.
threshold 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.
owners string[ ]

An array of the categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty.

classifier_ids string[ ]

An array that specifies which classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The following built-in classifier_ids require no training:

  • default: Returns classes from thousands of general tags.
  • food: (Beta) Enhances specificity and accuracy for images of food items.
  • explicit: (Beta) Evaluates whether the image might be pornographic.

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 object

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 object

{
   "classifier_ids":[
      "fruits_1462128776",
      "SatelliteModel_6242312846"
   ],
   "owners":["IBM"],
   "threshold":0.6
}

Request

Name Description
accept-language 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.
  • 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 ReadableStream, Buffer, FileObject An image file (.jpg, .png) or .zip file of images. Maximum image size is 10 MB. Include no more than 20 images and limit the .zip file to 100 MB. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters. You can also include an image with the url property in the parameters object.
images_file_content_type string The format (MIME type) of the uploaded 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.
parameters string

A string representation of a JSON object that specifies additional request options.Input parameters can include these inputs:

  • url: A string with the image URL to analyze. You can also include images in the images_file parameter.

  • threshold: A floating point value that specifies the minimum score a class must have to be returned in the response.

  • owners: An array of the categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

    The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty.

  • classifier_ids: An array that specifies which specific classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The following built-in classifier_ids require no training:

  • default: Returns classes from thousands of general tags.
  • food: (Beta) Enhances specificity and accuracy for images of food items.
  • explicit: (Beta) Evaluates whether the image might be pornographic.

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

let parameters = {
  classifier_ids: ["fruits_1462128776","SatelliteModel_6242312846"],
  threshold: 0.6
};

var params = {
  images_file: fs.createReadStream('./fruitbowl.jpg'),
  parameters: parameters
};

visual_recognition.classify(params, function(err, response) {
  if (err)
    console.log(err);
  else
    console.log(JSON.stringify(response, 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 10 MB. The maximum .zip file size is 100 MB with up to 20 images. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters.

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 format (MIME type) of the uploaded 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. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters.
parameters string

A string representation of a JSON object that specifies additional request options.Input parameters can include these inputs:

  • url: A string with the image URL to analyze. You can also include images in the imagesFilename parameter.

  • threshold: A floating point value that specifies the minimum score a class must have to be returned in the response.

  • owners: An array of the categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

    The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty.

  • classifier_ids: An array that specifies which specific classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The following built-in classifier_ids require no training:

  • default: Returns classes from thousands of general tags.
  • food: (Beta) Enhances specificity and accuracy for images of food items.
  • explicit: (Beta) Evaluates whether the image might be pornographic.

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\"],\"threshold\": 0.6}")
  .build();
ClassifiedImages result = service.classify(classifyOptions).execute();
System.out.println(result);

Request

Name Description
images_file file An image file (.jpg, .png) or .zip file of images. Maximum image size is 10 MB. Include no more than 20 images and limit the .zip file to 100 MB. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters. You can also include an image with the url property in the parameters object.
parameters string

A string representation of a JSON object that specifies additional request options.Input parameters can include these inputs:

  • url: A string with the image URL to analyze. You can also include images in the images_file parameter.

  • threshold: A floating point value that specifies the minimum score a class must have to be returned in the response.

  • owners: An array of the categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

    The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty.

  • classifier_ids: An array that specifies which specific classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty.

The following built-in classifier_ids require no training:

  • default: Returns classes from thousands of general tags.
  • food: (Beta) Enhances specificity and accuracy for images of food items.
  • explicit: (Beta) Evaluates whether the image might be pornographic.

accept-language 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.
  • 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_content_type string The format (MIME type) of the uploaded 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.
images_filename string The name of the image or .zip file. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters.

Example request

import json
from watson_developer_cloud import VisualRecognitionV3

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

with open('./fruitbowl.jpg', 'rb') as images_file:
    classes = visual_recognition.classify(
        images_file,
        parameters=json.dumps({
            'classifier_ids': ['fruits_1462128776','SatelliteModel_6242312846'],
            'threshold': 0.6
        }))
print(json.dumps(classes, 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 within the classifier.
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 Confidence score for the property 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
        }

Face

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 methods do not support general biometric facial recognition.

Tip: Try the updated Face model, which can provide more accurate results with facial analysis of age and gender. To use the beta model, replace /v3/detect_faces with /v3/detect_faces_beta in your requests. The Watson SDKs do not yet support the beta Face model.

GET /v3/detect_faces
POST /v3/detect_faces
ServiceCall<DetectedFaces> detectFaces(DetectFacesOptions detectFacesOptions)
detect_faces(images_file=None, parameters=None, images_file_content_type=None, images_filename=None)

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 IBM Cloud.

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

Name Description
images_file ReadableStream, Buffer, FileObject

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.

images_file_content_type string The format (MIME type) of the uploaded 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.
parameters string A string representation of a JSON object that specifies a single image (.jpg, .png) to analyze by URL. Example: {url: 'http://www.example.com/images/myimage.jpg'};.

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('./prez.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 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 string representation of a JSON object that specifies a single image (.jpg, .png) to analyze by URL. Example: {\"url\":\"http://www.example.com/images/myimage.jpg\"}.

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

Name Description
images_file 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 string A string representation of a JSON object that specifies a single image (.jpg, .png) to analyze by URL. Example: {url: 'http://www.example.com/images/myimage.jpg'};.
images_file_content_type string The format (MIME type) of the uploaded 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.
images_filename string The name of the image or .zip file. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters.

Example request

import json
from watson_developer_cloud import VisualRecognitionV3

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

with open('./prez.jpg', 'rb') as images_file:
    faces = visual_recognition.classify(images_file)
print(json.dumps(faces, 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

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.

Encode all names in UTF-8 if they contain non-ASCII characters (.zip and image file names, and classifier and class names). The service assumes UTF-8 encoding if it encounters non-ASCII characters.

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

POST /v3/classifiers
ServiceCall<Classifier> createClassifier(CreateClassifierOptions createClassifierOptions)
create_classifier(name, **kwargs)

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 number of images is 10,000 images or 100 MB per .zip file

Encode special characters in the file name in UTF-8.

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.

Encode special characters in the file name in UTF-8.

name form data string The name of the new classifier. Encode special characters in UTF-8.
Name Description
name string The name of the new classifier. Encode special characters in UTF-8.
{class}_positive_examples ReadableStream, Buffer, FileObject

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. You can either stream the .zip file or specify a file on disk.

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

Encode special characters in the file name in UTF-8.

negativeExamples ReadableStream, Buffer, FileObject

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.

Encode special characters in the file name in UTF-8.

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

Name Description
name string The name of the new classifier. Encode special characters in UTF-8.
addClass 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 number of images is 10,000 images or 100 MB per .zip file

Encode special characters in the file name in UTF-8.

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.

Encode special characters in the file name in UTF-8.

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

negativeExamplesFilename string The name of the .zip file. Encode special characters in the file name in UTF-8.
Name Description
name string The name of the new classifier. Encode special characters in UTF-8.
{class}_positive_examples 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. You can either stream the .zip file or specify a file on disk.

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

Encode special characters in the file name in UTF-8.

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.

Encode special characters in the file name in UTF-8.

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

Example request

curl -X POST -F "beagle_positive_examples=@beagle.zip" -F "goldenretriever_positive_examples=@golden-retriever.zip" -F "husky_positive_examples=@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: 'dogs',
  beagle_positive_examples: fs.createReadStream('./beagle.zip'),
  goldenretriever_positive_examples: fs.createReadStream('./golden-retriever.zip'),
  husky_positive_examples: fs.createReadStream('./husky.zip'),
  negative_examples: fs.createReadStream('./cats.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)
import json
from watson_developer_cloud import VisualRecognitionV3

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

with open('./beagle.zip', 'rb') as beagle, open(
        './golden-retriever.zip', 'rb') as goldenretriever, open(
            './husky.zip', 'rb') as husky, open(
                './cats.zip', 'rb') as cats:
    model = visual_recognition.create_classifier(
        'dogs',
        beagle_positive_examples=beagle,
        goldenretriever_positive_examples=goldenretriever,
        husky_positive_examples=husky,
        negative_examples=cats)
print(json.dumps(model, 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 string The ID of the new classifier.
name string The name of the new classifier.
owner string Unique ID of the account that owns the classifier.
status string The training status of the classifier of type Classifier.status. Valid values are ready, failed, or training.
explanation string If classifier training has failed, this field may explain why ,
created date Date and time in Coordinated Universal Time that the classifier was created.
classes object[ ] An array of class names that define the classifier.
Class (Java Classifier object)
Name Description
class string 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)
list_classifiers(verbose=None)

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.
Name Description
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({
  verbose: true
},
  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);
import json
from watson_developer_cloud import VisualRecognitionV3

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

classifiers = visual_recognition.list_classifiers(
    verbose=True)
print(json.dumps(classifiers, indent=2))

Response

Classifiers
Name Description
classifiers object[ ] An array of Classifier A list of Classifier objects that are available for the service instance.
Classifier (Java Classifier object)
Name Description
created date Date and time in Coordinated Universal Time that the classifier was created.
classifier_id string The ID of the classifier.
name string The name of the classifier.
status string The training status of the classifier of type Classifier.status. Valid values are ready, failed, training, or retraining.
owner string Unique ID of the account who owns the classifier. Returned only when verbose=true.
classes object[ ] An array of class names that define the classifier.
Class (Java Class object)
Name Description
class string 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"
    }
  ]
}
{
  "classifiers": [
    {
      "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)
get_classifier(classifier_id)

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
classifier_id string The unique identifier for a classifier.
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);
import json
from watson_developer_cloud import VisualRecognitionV3

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

classifier = visual_recognition.get_classifier(
    classifier_id='dogs_1477088859')
print(json.dumps(classifier, indent=2))

Response

Classifier (Java Classifier object)
Name Description
classifier_id string The ID of the specified classifier.
name string The name of the specified classifier.
owner string The ID of the account that owns the classifier.
status string The training status of the classifier of type Classifier. Valid values are ready, failed, training, or retraining.
created date Date and time in Coordinated Universal Time that the classifier was created.
classes object[ ] An array of class names that define the classifier.
Class (Java Class object)
Name Description
class string 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.

Encode all names in UTF-8 if they contain non-ASCII characters (.zip and image file names, and classifier and class names). The service assumes UTF-8 encoding if it encounters non-ASCII characters.

Important: You can't update a custom classifier with an API key for a Lite plan. To update a custom classifer on a Lite plan, create another service instance on a Standard plan and re-create your custom classifier.

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)
update_classifier(classifier_id, **kwargs)

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 identifier of the classifier that you want to update.
{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.

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

Encode special characters in the file name in UTF-8.

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.

Encode special characters in the file name in UTF-8.

Name Description
classifier_id string The ID of the classifier that you want to update.
{class}_positive_examples ReadableStream, Buffer, FileObject

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. You can either stream the .zip file or specify a file on disk.

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

Encode special characters in the file name in UTF-8.

negativeExamples ReadableStream, Buffer, FileObject

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.

Encode special characters in the file name in UTF-8.

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

Name Description
addClass 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 number of images is 10,000 images or 100 MB per .zip file.

Encode special characters in the file name in UTF-8.

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 specify a file on disk.

negativeExamplesFilename string The name of the .zip file. Encode special characters in the file name in UTF-8.
Name Description
classifier_id string The ID of the classifier that you want to update.
{class}_positive_examples 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. You can either stream the .zip file or specify a file on disk.

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

Encode special characters in the file name in UTF-8.

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.

Encode special characters in the file name in UTF-8.

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

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.

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 = {
  classifier_id: 'dogs_1477088859',
  dalmatian_positive_examples: fs.createReadStream('./dalmatian.zip'),
  negative_examples: fs.createReadStream('./more-cats.zip')
};

visual_recognition.updateClassifier(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");
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);
import json
from watson_developer_cloud import VisualRecognitionV3

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

with open('./dalmatian.zip', 'rb') as dalmatian, open(
        './more-cats.zip', 'rb') as more_cats:
    updated_model = visual_recognition.update_classifier(
        classifier_id='dogs_1477088859',
        dalmatian_positive_examples=dalmatian,
        negative_examples=more_cats)
print(json.dumps(updated_model, indent=2))
                

Response

Name Description
classifier_id string The ID of the new classifier.
name string The name of the new classifier.
owner string Unique ID of the account who owns the classifier.
status string The training status of the classifier. Valid values are ready, failed, training, or retraining.
explanation string Omitted if the classifier trains successfully. If the classifier training fails, this might explain why training failed.
created date Date and time in Coordinated Universal Time that the classifier was created.
classes object[ ] An array of class names that define the classifier.
retrained date Date and time in Coordinated Universal Time that the classifier was updated.
Class (Java Classifier object)
Name Description
class string 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)
delete_classifier(classifier_id)

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
classifier_id 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();
import json
from watson_developer_cloud import VisualRecognitionV3

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

response = visual_recognition.delete_classifier(classifier_id='dogs_1477088859')
print(json.dumps(response, 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.

Example request

curl -H "X-Watson-Learning-Opt-Out: true" -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 request

var watson = require('watson-developer-cloud');
var visual_recognition = watson.visual_recognition({
  api_key: '{api-key}',
  version_date: '2016-05-20'
  headers: {
    "X-Watson-Learning-Opt-Out": true
  }
});

Example request

VisualRecognition service = new VisualRecognition(
  VisualRecognition.VERSION_DATE_2016_05_20
);
Map<String, String> headers = new HashMap<String, String>();
headers.put(HttpHeaders.X_WATSON_LEARNING_OPT_OUT, "1");
service.setDefaultHeaders(headers);

Example request

import watson_developer_cloud

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

visual_recognition.set_default_headers({'x-watson-learning-opt-out': "true"})

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 successful 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
403 - Forbidden No API key, or the key is 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.