Curl Node Java Python

Visual Recognition

API reference

Introduction

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

For details about using Visual Recognition, see the IBM® Cloud docs.

Authentication

IBM Cloud is migrating to token-based Identity and Access Management (IAM) authentication.

You authenticate to the API by using IAM. You can pass either a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. Learn more about IAM.

To find out which authentication to use, view the service credentials by clicking the service instance on the Dashboard.

IAM authentication. Replace {apikey} with your service credentials.


curl -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/v3/{method}"
        

Basic authentication. Replace {api_key} with your service credentials.


curl "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/{method}?api_key={api_key}"
        

Service endpoint

Visual Recognition is hosted only in the US South location and has a single service endpoint. The URL is different when you use IBM Cloud Dedicated.

API endpoint

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

Use "gateway-a.watsonplatform.net" for Visual Recognition instances created before May 23, 2018.

Default URL

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

Examples for the US East location in the constructor and after instantiation


VisualRecognition visualRecognition = new VisualRecognition("{version}");
visualRecognition.setEndPoint("https://gateway-wdc.watsonplatform.net/visual-recognition/api");
                

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

var visualRecognition = new ({
    version: '{version}',
    iam_apikey: '{iam_api_key}',
    url: 'https://gateway-wdc.watsonplatform.net/visual-recognition/api'
});
    
                    

visual_recognition = (
    version='{version}',
    iam_apikey='{iam_api_key}',
    url='https://gateway-wdc.watsonplatform.net/visual-recognition/api'
)

                    

or


visual_recognition.set_url('https://gateway-wdc.watsonplatform.net/visual-recognition/api')
                    

visual_recognition = IBMWatson::.new(
  version: "{version}",
    iam_apikey: "{iam_api_key}",
  url: "https://gateway-wdc.watsonplatform.net/visual-recognition/api"
)

                    

or


visual_recognition.url = "https://gateway-wdc.watsonplatform.net/visual-recognition/api"
                

let visualRecognition = VisualRecognition("{api-key}", version: "{version}")
visualRecognition.serviceURL = "{url}"
                    

Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. When we change the API in a backwards-incompatible way, we release a new version date.

Send the version parameter with every API request. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

Specify the version to use on API requests with the version parameter when you create the service instance. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

Error handling

The Visual Recognition service uses standard HTTP response codes to indicate 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. Response codes are listed with the method.

ErrorResponse
Name Description
code integer

HTTP error code.

error string

Human-readable error string, like 'Invalid image file'.

ErrorAuthentication
Name Description
status string

The status of error.

statusInfo string

Information about the error.

ErrorHTML
Name Description
Error string

HTML description of the error.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code integer

HTTP status code.

description string

Human-readable error description. For example, File size limit exceeded.

error_id string

Codified error string. For example, limit_exceeded.

Data handling

Data labels

You can remove customer data if you associate the customer and the data when you send the information to a service. First you label the data with a customer ID, and then you can delete the data by the ID.

  • Use the X-Watson-Metadata header to associate a customer ID with the data. By adding a customer ID to a request, you indicate that it contains data that belongs to that customer.

    Specify a random or generic string for the customer ID. Do not include personal data, such as an email address. Pass the string customer_id={id} as the argument of the header. For more information about how to pass headers, see Additional headers.

  • Use the Delete labeled data method to remove data that is associated with a customer ID.

Labeling data is used only by methods that accept customer data. For more information about Visual Recognition and labeling data, see Information security.

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 request header 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. To prevent IBM from accessing your data 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.) You can set the header using the setDefaultHeaders method of the service object. You can set the header using the headers parameter when you create the service object. You can set the header using the set_default_headers method of the service object. You can set the header by using the add_default_headers method of the service object.

Example request


curl -u "apikey:{apikey}" -H "X-Watson-Learning-Opt-Out: true" "https://gateway.watsonplatform.net/visual-recognition/api/v3/{method}"
            

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

visualRecognition.setDefaultHeaders(headers);
            

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

var visualRecognition = new ({
  version: '{version}',
  iam_apikey: '{iam_api_key}',
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});
            

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

visual_recognition.add_default_headers(headers: {"x-watson-learning-opt-out" => "true"})
            

let visualRecognition = VisualRecognition(apiKey: "{iam_api_key}")
visualRecognition.defaultHeaders = ["X-Watson-Learning-Opt-Out": "true"]
            

General

Classify an image

Classify an image with the built-in or custom classifiers.

Request

GET /v3/classify
Parameter Description
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 2018-03-19.

Accept-Language header string

The language of the output class names. The full set of languages is supported for the built-in classifier IDs: default, food, and explicit. The class names of custom classifiers are not translated.

The response might not be in the specified language when the requested language is not supported or when there is no translation for the class name.

Allowable values:
  • en
  • ar
  • de
  • es
  • fr
  • it
  • ja
  • ko
  • pt-br
  • zh-cn
  • zh-tw

en

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.

owners query string[]

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.

Allowable values:
  • IBM
  • me
classifier_ids query string[]

Which classifiers to apply. Overrides the owners parameter. You can specify both custom and built-in classifier IDs. 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: Enhances specificity and accuracy for images of food items.
  • explicit: Evaluates whether the image might be pornographic.
threshold query float

The minimum score a class must have to be returned.

0.5

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classify?url=https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/fruitbowl.jpg&version=2018-03-19"
        

Response

ClassifiedImages

Results for all images.

Name Description
custom_classes integer

Number of custom classes identified in the images.

images_processed integer

Number of images processed for the API call.

images ClassifiedImage[]

Classified images.

warnings WarningInfo[]

Information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.

ClassifiedImage

Results for one image.

Name Description
source_url string

Source of the image before any redirects. Not returned when the image is uploaded.

resolved_url string

Fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded.

image string

Relative path of the image file if uploaded directly. Not returned when the image is passed by URL.

error ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

classifiers ClassifierResult[]

The classifiers.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code integer

HTTP status code.

description string

Human-readable error description. For example, File size limit exceeded.

error_id string

Codified error string. For example, limit_exceeded.

ClassifierResult

Classifier and score combination.

Name Description
name string

Name of the classifier.

classifier_id string

ID of a classifier identified in the image.

classes ClassResult[]

Classes within the classifier.

ClassResult

Result of a class within a classifier.

Name Description
class string

Name of the class.

score float

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

Knowledge graph of the property. For example, /fruit/pome/apple/eating apple/Granny Smith. Included only if identified.

WarningInfo

Information about something that went wrong.

Name Description
warning_id string

Codified warning string, such as limit_reached.

description string

Information about the error.

Example response


{
  "images" : [ {
    "classifiers" : [ {
      "classifier_id" : "default",
      "name" : "default",
      "classes" : [ {
        "class" : "diet (food)",
        "score" : 0.571,
        "type_hierarchy" : "/food/diet (food)"
      }, {
        "class" : "food",
        "score" : 0.571
      }, {
        "class" : "fruit",
        "score" : 0.825
      }, {
        "class" : "banana",
        "score" : 0.518,
        "type_hierarchy" : "/fruit/banana"
      }, {
        "class" : "Granny Smith",
        "score" : 0.5,
        "type_hierarchy" : "/fruit/pome/apple/eating apple/Granny Smith"
      }, {
        "class" : "eating apple",
        "score" : 0.64
      }, {
        "class" : "apple",
        "score" : 0.655
      }, {
        "class" : "pome",
        "score" : 0.669
      }, {
        "class" : "Golden Delicious",
        "score" : 0.5,
        "type_hierarchy" : "/fruit/pome/apple/eating apple/Golden Delicious"
      }, {
        "class" : "olive color",
        "score" : 0.942
      }, {
        "class" : "lemon yellow color",
        "score" : 0.9
      } ]
    } ],
    "source_url" : "https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/fruitbowl.jpg",
    "resolved_url" : "https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/fruitbowl.jpg"
  } ],
  "images_processed" : 1,
  "custom_classes" : 0
}
        

Response Codes

Status Description
200

success

400

Invalid request due to user input, for example:

  • Bad header parameter
  • Invalid output language
  • No input images
  • The size of the image file in the request is larger than the maximum supported size
403

No API key, or the key is not valid.

Classify images

Classify images with built-in or custom classifiers.

Request

POST /v3/classify
Parameter Description
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 2018-03-19.

images_file form file

An image file (.jpg, .png) or .zip file with 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 parameter.

Accept-Language header string

The language of the output class names. The full set of languages is supported for the built-in classifier IDs: default, food, and explicit. The class names of custom classifiers are not translated.

The response might not be in the specified language when the requested language is not supported or when there is no translation for the class name.

Allowable values:
  • en
  • ar
  • de
  • es
  • fr
  • it
  • ja
  • ko
  • pt-br
  • zh-cn
  • zh-tw

en

url form string

The URL of an image 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 with the images_file parameter.

threshold form float

The minimum score a class must have to be displayed in the response. Set the threshold to 0.0 to ignore the classification score and return all values.

0.5

owners form string[]

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 form string[]

Which classifiers to apply. Overrides the owners parameter. You can specify both custom and built-in classifier IDs. 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: Enhances specificity and accuracy for images of food items.
  • explicit: Evaluates whether the image might be pornographic.
api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request with Custom models

curl -X POST -u "apikey:{apikey}" -F "images_file=@fruitbowl.jpg" -F "threshold=0.6" -F "owners=me" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classify?version=2018-03-19"
        

Download example image fruitbowl.jpg

Example request with the built-in Food model

curl -X POST -u "apikey:{apikey}" -F "classifier_ids=food" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classify?version=2018-03-19"
        

Response

ClassifiedImages

Results for all images.

Name Description
custom_classes integer

Number of custom classes identified in the images.

images_processed integer

Number of images processed for the API call.

images ClassifiedImage[]

Classified images.

warnings WarningInfo[]

Information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.

ClassifiedImage

Results for one image.

Name Description
source_url string

Source of the image before any redirects. Not returned when the image is uploaded.

resolved_url string

Fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded.

image string

Relative path of the image file if uploaded directly. Not returned when the image is passed by URL.

error ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

classifiers ClassifierResult[]

The classifiers.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code integer

HTTP status code.

description string

Human-readable error description. For example, File size limit exceeded.

error_id string

Codified error string. For example, limit_exceeded.

ClassifierResult

Classifier and score combination.

Name Description
name string

Name of the classifier.

classifier_id string

ID of a classifier identified in the image.

classes ClassResult[]

Classes within the classifier.

ClassResult

Result of a class within a classifier.

Name Description
class string

Name of the class.

score float

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

Knowledge graph of the property. For example, /fruit/pome/apple/eating apple/Granny Smith. Included only if identified.

WarningInfo

Information about something that went wrong.

Name Description
warning_id string

Codified warning string, such as limit_reached.

description string

Information about the error.

Example response


{
  "images" : [ {
    "classifiers" : [ {
      "classifier_id" : "default",
      "name" : "default",
      "classes" : [ {
        "class" : "fruit",
        "score" : 0.788
      }, {
        "class" : "olive color",
        "score" : 0.973
      }, {
        "class" : "lemon yellow color",
        "score" : 0.789
      } ]
    } ],
    "image" : "fruitbowl.jpg"
  } ],
  "images_processed" : 1,
  "custom_classes" : 2
}
        

Response Codes

Status Description
200

success

400

Invalid request due to user input, for example:

  • Bad JSON input
  • Bad query parameter or header
  • Invalid output language
  • No input images
  • The size of the image file in the request is larger than the maximum supported size
  • Corrupt .zip file
403

No API key, or the key is not valid.

413

The .zip file is too large.

Face

Detect faces in an image

Important: On April 2, 2018, the identity information in the response to calls to the Face model was removed. The identity information refers to the name of the person, score, and type_hierarchy knowledge graph. For details about the enhanced Face model, see the Release notes.

Analyze and get data about faces in images. Responses can include estimated age and gender. This feature uses a built-in model, so no training is necessary. The Detect faces method does not support general biometric facial recognition.

Supported image formats include .gif, .jpg, .png, and .tif. The maximum image size is 10 MB. The minimum recommended pixel density is 32X32 pixels per inch.

Request

GET /v3/detect_faces
Parameter Description
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 2018-03-19.

url query string

The URL of an image to analyze. Must be in .gif, .jpg, .png, or .tif format. 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.

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/v3/detect_faces?url=https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/Ginni_Rometty_at_the_Fortune_MPW_Summit_in_2011.jpg&version=2018-03-19"
        

Response

DetectedFaces

Results for all faces.

Name Description
images_processed integer

Number of images processed for the API call.

images ImageWithFaces[]

The images.

warnings WarningInfo[]

Information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.

ImageWithFaces

Information about faces in the image.

Name Description
faces Face[]

Faces detected in the images.

image string

Relative path of the image file if uploaded directly. Not returned when the image is passed by URL.

source_url string

Source of the image before any redirects. Not returned when the image is uploaded.

resolved_url string

Fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded.

error ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Face

Information about the face.

Name Description
age FaceAge

Age information about a face.

gender FaceGender

Information about the gender of the face.

face_location FaceLocation

The location of the bounding box around the face.

FaceAge

Age information about a face.

Name Description
min integer

Estimated minimum age.

max integer

Estimated maximum age.

score float

Confidence score in the range of 0 to 1. A higher score indicates greater confidence in the estimated value for the property.

FaceGender

Information about the gender of the face.

Name Description
gender string

Gender identified by the face. For example, MALE or FEMALE.

score float

Confidence score in the range of 0 to 1. A higher score indicates greater confidence in the estimated value for the property.

FaceLocation

The location of the bounding box around the face.

Name Description
width number

Width in pixels of face region.

height number

Height in pixels of face region.

left number

X-position of top-left pixel of face region.

top number

Y-position of top-left pixel of face region.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code integer

HTTP status code.

description string

Human-readable error description. For example, File size limit exceeded.

error_id string

Codified error string. For example, limit_exceeded.

WarningInfo

Information about something that went wrong.

Name Description
warning_id string

Codified warning string, such as limit_reached.

description string

Information about the error.

Example response


{
  "images" : [ {
    "faces" : [ {
      "age" : {
        "min" : 50,
        "max" : 53,
        "score" : 0.33788413
      },
      "face_location" : {
        "height" : 744,
        "width" : 606,
        "left" : 460,
        "top" : 373
      },
      "gender" : {
        "gender" : "FEMALE",
        "score" : 0.9999988
      }
    } ],
    "resolved_url" : "https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/Ginni_Rometty_at_the_Fortune_MPW_Summit_in_2011.jpg",
    "source_url" : "https://watson-developer-cloud.github.io/doc-tutorial-downloads/visual-recognition/Ginni_Rometty_at_the_Fortune_MPW_Summit_in_2011.jpg"
  } ],
  "images_processed" : 1
}
        

Response Codes

Status Description
200

success

400

Invalid request

Detect faces in images

Important: On April 2, 2018, the identity information in the response to calls to the Face model was removed. The identity information refers to the name of the person, score, and type_hierarchy knowledge graph. For details about the enhanced Face model, see the Release notes.

Analyze and get data about faces in images. Responses can include estimated age and gender. This feature uses a built-in model, so no training is necessary. The Detect faces method does not support general biometric facial recognition.

Supported image formats include .gif, .jpg, .png, and .tif. The maximum image size is 10 MB. The minimum recommended pixel density is 32X32 pixels per inch.

Request

POST /v3/detect_faces
Parameter Description
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 2018-03-19.

images_file form file

An image file (gif, .jpg, .png, .tif.) or .zip file with images. Limit the .zip file to 100 MB. You can include a maximum of 15 images in a request.

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

url form string

The URL of an image to analyze. Must be in .gif, .jpg, .png, or .tif format. 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.

You can also include images with the images_file parameter.

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -X POST -u "apikey:{apikey}" -F "images_file=@Ginni_Rometty.jpg" "https://gateway.watsonplatform.net/visual-recognition/api/v3/detect_faces?version=2018-03-19"
        

Download example image Ginni_Rometty.jpg

Response

DetectedFaces

Results for all faces.

Name Description
images_processed integer

Number of images processed for the API call.

images ImageWithFaces[]

The images.

warnings WarningInfo[]

Information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.

ImageWithFaces

Information about faces in the image.

Name Description
faces Face[]

Faces detected in the images.

image string

Relative path of the image file if uploaded directly. Not returned when the image is passed by URL.

source_url string

Source of the image before any redirects. Not returned when the image is uploaded.

resolved_url string

Fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded.

error ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Face

Information about the face.

Name Description
age FaceAge

Age information about a face.

gender FaceGender

Information about the gender of the face.

face_location FaceLocation

The location of the bounding box around the face.

FaceAge

Age information about a face.

Name Description
min integer

Estimated minimum age.

max integer

Estimated maximum age.

score float

Confidence score in the range of 0 to 1. A higher score indicates greater confidence in the estimated value for the property.

FaceGender

Information about the gender of the face.

Name Description
gender string

Gender identified by the face. For example, MALE or FEMALE.

score float

Confidence score in the range of 0 to 1. A higher score indicates greater confidence in the estimated value for the property.

FaceLocation

The location of the bounding box around the face.

Name Description
width number

Width in pixels of face region.

height number

Height in pixels of face region.

left number

X-position of top-left pixel of face region.

top number

Y-position of top-left pixel of face region.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code integer

HTTP status code.

description string

Human-readable error description. For example, File size limit exceeded.

error_id string

Codified error string. For example, limit_exceeded.

WarningInfo

Information about something that went wrong.

Name Description
warning_id string

Codified warning string, such as limit_reached.

description string

Information about the error.

Example response


{
  "images" : [ {
    "faces" : [ {
      "age" : {
        "min" : 50,
        "max" : 53,
        "score" : 0.33788413
      },
      "face_location" : {
        "height" : 744,
        "width" : 606,
        "left" : 460,
        "top" : 373
      },
      "gender" : {
        "gender" : "FEMALE",
        "score" : 0.9999988
      }
    } ],
    "image" : "Ginni_Rometty.jpg"
  } ],
  "images_processed" : 1
}
        

Response Codes

Status Description
200

success

400

Invalid request

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.

Request

POST /v3/classifiers
Parameter Description
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 2018-03-19.

name form string

The name of the new classifier. Encode special characters in UTF-8.

classname_positive_examples form 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.

Specify the parameter name by appending _positive_examples to 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 file

A .zip file of images that do not depict the visual subject of any of the classes of the new classifier. Must contain a minimum of 10 images.

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

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -X POST -u "apikey:{apikey}" -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.watsonplatform.net/visual-recognition/api/v3/classifiers?version=2018-03-19"
        

Download positive examples files beagle.zip, golden-retriever.zip, husky.zip

Download negative examples file cats.zip

Response

Classifier

Information about a classifier.

Name Description
classifier_id string

ID of a classifier identified in the image.

name string

Name of the classifier.

owner string

Unique ID of the account who owns the classifier. Returned when verbose=true. Might not be returned by some requests.

status string

Training status of classifier.

Possible values:
  • ready
  • training
  • retraining
  • failed
core_ml_enabled boolean

Whether the classifier can be downloaded as a Core ML model after the training status is ready.

explanation string

If classifier training has failed, this field may explain why.

created DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was created.

classes Class[]

Classes that define a classifier.

retrained DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was updated. Returned when verbose=true. Might not be returned by some requests. Identical to updated and retained for backward compatibility.

updated DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was most recently updated. The field matches either retrained or created. Returned when verbose=true. Might not be returned by some requests.

Class

A category within a classifier.

Name Description
class string

The name of the class.

Example response


{
  "classifier_id" : "dogs_1477088859",
  "name" : "dogs",
  "status" : "training",
  "owner" : "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
  "created" : "2018-03-17T19:01:30.536Z",
  "updated" : "2018-03-17T19:01:30.536Z",
  "classes" : [ {
    "class" : "husky"
  }, {
    "class" : "goldenretriever"
  }, {
    "class" : "beagle"
  } ],
  "core_ml_enabled" : true
}
        

Response Codes

Status Description
200

success

400

Invalid request due to user input, for example:

  • Bad query parameter or header
  • No input images
  • The size of the image file in the request is larger than the maximum supported size
  • Corrupt .zip file
  • Cannot find the classifier
403

No API key, or the key is not valid.

413

The .zip file is too large.

Retrieve a list of classifiers

Request

GET /v3/classifiers
Parameter Description
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 2018-03-19.

verbose query boolean

Specify true to return details about the classifiers. Omit this parameter to return a brief list of classifiers.

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classifiers?verbose=true&version=2018-03-19"
        

Response

Classifiers

A container for the list of classifiers.

Name Description
classifiers Classifier[]

List of classifiers.

Classifier

Information about a classifier.

Name Description
classifier_id string

ID of a classifier identified in the image.

name string

Name of the classifier.

owner string

Unique ID of the account who owns the classifier. Returned when verbose=true. Might not be returned by some requests.

status string

Training status of classifier.

Possible values:
  • ready
  • training
  • retraining
  • failed
core_ml_enabled boolean

Whether the classifier can be downloaded as a Core ML model after the training status is ready.

explanation string

If classifier training has failed, this field may explain why.

created DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was created.

classes Class[]

Classes that define a classifier.

retrained DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was updated. Returned when verbose=true. Might not be returned by some requests. Identical to updated and retained for backward compatibility.

updated DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was most recently updated. The field matches either retrained or created. Returned when verbose=true. Might not be returned by some requests.

Class

A category within a classifier.

Name Description
class string

The name of the class.

Example response


{
  "classifiers" : [ {
    "classifier_id" : "dogs_1477088859",
    "name" : "dogs",
    "status" : "ready",
    "owner" : "99d0114d-9959-4071-b06f-654701909be4",
    "created" : "2018-03-17T19:01:30.536Z",
    "updated" : "2018-03-17T19:42:19.906Z",
    "classes" : [ {
      "class" : "husky"
    }, {
      "class" : "goldenretriever"
    }, {
      "class" : "beagle"
    } ],
    "core_ml_enabled" : true
  }, {
    "classifier_id" : "CarsvsTrucks_1479118188",
    "name" : "Cars vs Trucks",
    "status" : "ready",
    "owner" : "99d0114d-9959-4071-b06f-654701909be4",
    "created" : "2016-07-19T15:24:08.743Z",
    "updated" : "2016-07-19T15:24:08.743Z",
    "classes" : [ {
      "class" : "cars"
    } ],
    "core_ml_enabled" : false
  } ]
}
        

Response Codes

Status Description
200

success

400

Invalid request due to user input, such as a bad parameter.

403

No API key, or the key is not valid.

Retrieve classifier details

Retrieve information about a custom classifier.

Request

GET /v3/classifiers/{classifier_id}
Parameter Description
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 2018-03-19.

classifier_id path string

The ID of the classifier.

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859?version=2018-03-19"
        

Response

Classifier

Information about a classifier.

Name Description
classifier_id string

ID of a classifier identified in the image.

name string

Name of the classifier.

owner string

Unique ID of the account who owns the classifier. Returned when verbose=true. Might not be returned by some requests.

status string

Training status of classifier.

Possible values:
  • ready
  • training
  • retraining
  • failed
core_ml_enabled boolean

Whether the classifier can be downloaded as a Core ML model after the training status is ready.

explanation string

If classifier training has failed, this field may explain why.

created DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was created.

classes Class[]

Classes that define a classifier.

retrained DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was updated. Returned when verbose=true. Might not be returned by some requests. Identical to updated and retained for backward compatibility.

updated DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was most recently updated. The field matches either retrained or created. Returned when verbose=true. Might not be returned by some requests.

Class

A category within a classifier.

Name Description
class string

The name of the class.

Example response


{
  "classifier_id" : "dogs_1477088859",
  "name" : "dogs",
  "status" : "training",
  "owner" : "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
  "created" : "2018-03-17T19:01:30.536Z",
  "updated" : "2018-03-17T19:01:30.536Z",
  "classes" : [ {
    "class" : "husky"
  }, {
    "class" : "goldenretriever"
  }, {
    "class" : "beagle"
  } ],
  "core_ml_enabled" : true
}
        

Response Codes

Status Description
200

success

400

Invalid request due to user input, such as a bad parameter.

403

No API key, or the key is not valid.

404

Cannot find the requested classifier in this account.

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. For details, see Updating custom classifiers.

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.

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.

Request

POST /v3/classifiers/{classifier_id}
Parameter Description
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 2018-03-19.

classifier_id path string

The ID of the classifier.

classname_positive_examples form 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.

Specify the parameter name by appending _positive_examples to 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 file

A .zip file of images that do not depict the visual subject of any of the classes of the new classifier. Must contain a minimum of 10 images.

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

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -X POST -u "apikey:{apikey}" -F "dalmatian_positive_examples=@dalmatian.zip" -F "negative_examples=@more-cats.zip" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859?version=2018-03-19"
        

Download positive examples file dalmatian.zip

Download negative examples file more-cats.zip

Response

Classifier

Information about a classifier.

Name Description
classifier_id string

ID of a classifier identified in the image.

name string

Name of the classifier.

owner string

Unique ID of the account who owns the classifier. Returned when verbose=true. Might not be returned by some requests.

status string

Training status of classifier.

Possible values:
  • ready
  • training
  • retraining
  • failed
core_ml_enabled boolean

Whether the classifier can be downloaded as a Core ML model after the training status is ready.

explanation string

If classifier training has failed, this field may explain why.

created DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was created.

classes Class[]

Classes that define a classifier.

retrained DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was updated. Returned when verbose=true. Might not be returned by some requests. Identical to updated and retained for backward compatibility.

updated DateTime

Date and time in Coordinated Universal Time (UTC) that the classifier was most recently updated. The field matches either retrained or created. Returned when verbose=true. Might not be returned by some requests.

Class

A category within a classifier.

Name Description
class string

The name of the class.

Example response


{
  "classifier_id" : "dogs_1477088859",
  "name" : "dogs",
  "status" : "retraining",
  "owner" : "b2a3c43c-f1ef-4186-a3d3-71073e4142c5",
  "created" : "2018-03-17T19:01:30.536Z",
  "updated" : "2018-03-17T19:01:30.536Z",
  "classes" : [ {
    "class" : "husky"
  }, {
    "class" : "goldenretriever"
  }, {
    "class" : "beagle"
  }, {
    "class" : "dalmatian"
  } ],
  "core_ml_enabled" : true
}
        

Response Codes

Status Description
200

success

400

Invalid request due to user input, for example:

  • Bad query parameter or header
  • No input images
  • The size of the image file in the request is larger than the maximum supported size
  • Corrupt .zip file
  • Cannot find the classifier
403

No API key, or the key is not valid.

413

The .zip file is too large.

Delete a classifier

Request

DELETE /v3/classifiers/{classifier_id}
Parameter Description
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 2018-03-19.

classifier_id path string

The ID of the classifier.

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request

curl -X DELETE -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859?version=2018-03-19"
        

Response

Response type: Empty.

Response Codes

Status Description
200

success

400

Invalid request due to user input, such as a bad parameter.

403

No API key, or the key is not valid.

404

Cannot find the requested classifier in this account.

Core ML

Retrieve a Core ML model of a classifier

Download a Core ML model file (.mlmodel) of a custom classifier that returns "core_ml_enabled": true in the classifier details.

Request

GET /v3/classifiers/{classifier_id}/core_ml_model
Parameter Description
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 2018-03-19.

classifier_id path string

The ID of the classifier.

api_key query string

API key. Deprecated. Used only with service instances created before May 23, 2018. Other instances use IAM.

Example request with output file

curl -u "apikey:{apikey}" --output dogs_1477088859.mlmodel "https://gateway.watsonplatform.net/visual-recognition/api/v3/classifiers/dogs_1477088859/core_ml_model?version=2018-03-19"
        

Response

Response type: file.

Response Codes

Status Description
200

The request succeeded.

400

Invalid request due to user input, such as a bad parameter.

403

No API key, or the key is not valid.

404

Cannot find the requested classifier in this account.

User data

Delete labeled data

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Request

DELETE /v3/user_data
Parameter Description
customer_id query string

The customer ID for which all data is to be deleted.

Example request

curl -X DELETE -u "apikey:{apikey}" "https://gateway.watsonplatform.net/visual-recognition/api/user_data?customer_id=customer&version=2018-03-19"
        

Response

Response type: Empty.

Response Codes

Status Description
202

The request to delete data was successfully submitted.

400

Invalid request due to user input, such as a bad parameter.