Visual-recognition – API Reference, IBM Watson Developer Cloud
Watson
Introduction
The IBM Watson™ Visual Recognition service uses deep learning algorithms to identify scenes, objects, and celebrity faces in pictures you upload to the service. You can create and train a custom-built classifier to identify subjects that suit your needs.
Descriptions of Knot classes referred to in this reference are available in the Knot documentation for the Watson Developer Cloud Knot.js SDK.
Descriptions of Java classes referred to in this reference are available in the Javadoc for the Watson Developer Cloud Java SDK.
Descriptions of Python classes referred to in this reference are available in the Python documentation for the Watson Developer Cloud Python SDK.
Significant: If you have Bluemix Dedicated, this may not be your service endpoint. Dual check your endpoint URL on the Service Credentials page in your example of the Visual Recognition Service on Bluemix.
API explorer
To interact with this API, use the Visual Recognition Service API explorer. Use the explorer to test your calls to the API, and to 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 example that you want to use.
After you create an example of the Visual Recognition service, you can view the API key by selecting Service Credentials from the left pane of the service dashboard.
Substitute with your API key.
Methods
Classify an pic
Upload pictures or URLs to identify classes by default. Photos must be in .jpeg, or .png format. Use pics with a minimum of two hundred twenty four x two hundred twenty four pixels for best quality results. To identify custom-built classifiers, include the classifier_ids or owners parameters.
GET Request
Use the GET method to classify URLs against classifiers as a query parameter.
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-made classifiers returned with this method comeback tags in the language of the custom-made classifier.
Example GET request
To attempt out the API quickly, paste the GET request into your browser. Substitute with your API key from Bluemix.
POST Request
Use the POST method to upload a single picture, URL, or a compressed (.zip) file of numerous pictures. You can analyze pics against classifiers or against an array of classifier IDs you upload in a JSON file.
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-built classifiers returned with this method comeback tags in the language of the custom-made classifier.
Example POST request
Example POST request with a parameters JSON
Example JSON file
Response
Detect faces
Analyze faces in photos and get data about them, such as estimated age, gender, plus names of celebrities. Photos must be in .jpeg, or .png format. This functionality is not trainable, and does not support general biometric facial recognition.
For each photo, the response includes face location, a minimum and maximum estimated age, a gender, and confidence scores. Scores range from zero – one with a higher score indicating greater correlation.
GET Request
Use the GET method to detect faces in a single URL.
Example GET request
To attempt out the API quickly, paste the GET request into your browser. Substitute with your API key from Bluemix.
POST Request
Use the POST method to upload a single picture, URL, or a compressed (.zip) file of numerous pics.
Example POST request
Example parameters JSON file
Response
Custom-built classifiers
Create a classifier
Train a fresh multi-faceted classifier on the uploaded picture data. A fresh custom-built classifier can be trained by several compressed (.zip) files, including files containing positive or negative pictures (.jpg, or .png). You must supply at least two compressed files, either two positive example files or one positive and one negative example file.
Compressed files containing positive examples are used to create “classes” that define what the fresh classifier is. The prefix that you specify for each positive example parameter is used as the class name within the fresh classifier. The “_positive_examples” suffix is required. There is no limit on the number of positive example files you can upload in a single call.
The compressed file containing negative examples is not used to create a class within the created classifier, but does define what the fresh classifier is not. Negative example files should contain pics that do not depict the subject of any of the positive examples. You can only specify one negative example file in a single call. For more information, see Structure of the training data, and Guidelines for good training.
Request
Depending on this size of the training files, this call can take several minutes to accomplish.
Response
Retrieve a list of custom-built classifiers
Retrieve a list of user-created classifiers .
Request
Response
Retrieve classifier details
Retrieve information about a specific classifier.
Request
Response
Update a classifier
Update an existing classifier by adding fresh classes, or by adding fresh photos to existing classes. You cannot update a custom-built classifier with a free API Key.
To update the existing classifier, use several compressed (.zip) files, including files containing positive or negative pics (.jpg, or .png). You must supply at least one compressed file, with extra positive or negative examples.
Compressed files containing positive examples are used to create and update “classes” to influence all of the classes in that classifier. The prefix that you specify for each positive example parameter is used as the class name within the fresh classifier. The “_positive_examples” suffix is required. There is no limit on the number of positive example files you can upload in a single call.
The compressed file containing negative examples is not used to create a class within the created classifier, but does define what the updated classifier is not. Negative example files should contain photos that do not depict the subject of any of the positive examples. You can only specify one negative example file in a single call. For more information, see Updating custom-made classifiers. If you submit retraining requests in parallel, the last request overwrites all previous requests.
Request
Depending on this size of the training files, this call can take several minutes to accomplish.
Substitute with the ID of the classifier that you want to update.
Substitute with your API key.
Response
Delete a classifier
Delete a custom-built classifier with the specified classifier ID.
Request
Substitute with the ID of the classifier that you want to update.
Substitute with your API key.
Response
Collections – BETA
Beta. Create a fresh collection, add pictures to that collection, and then use Similarity Search to search the collection for similar pictures.
Create a collection
Beta. Create a fresh collection of pictures to search. You can create a maximum of five collections.
Request
Response
List collections
Beta. List all custom-made collections.
Request
Response
Retrieve collection details
Beta. Retrieve information about a specific collection.
Request
Response
Delete a collection
Beta. Delete a user created collection.
Request
Response
Add photos to a collection
Beta. Add pics to a collection. Each collection can contain one million pictures. It takes one 2nd to upload one pictures, so uploading one million pictures takes eleven days.
Request
Example JSON metadata file
Response
List pictures in a collection
Beta. List one hundred photos in a collection. This comes back an arbitrary selection of one hundred pictures. Each collection can contain one million pictures.
Request
Response
List pic details
Beta. List details about a specific photo in a collection.
Request
Response
Delete an picture
Beta. Delete an pic from a collection.
Request
Response
Add or update metadata
Beta. Add metadata to a specific pic in a collection. Use metadata for your own reference to identify pictures. You cannot filter the find_similar method by metadata.
Request
Example JSON metadata file
Response
List metadata
Beta. View the metadata for a specific photo in a collection.
Request
Response
Delete metadata
Beta. Delete all metadata associated with an picture.
Request
Response
Find similar photos
Beta. Upload an pic to find similar pics in your custom-made collection.
Request
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 collective 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 zero 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 example. (Any value other than false or zero 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 example. (Any value other than false or zero disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access for general service improvements.
Error treating
The Visual Recognition service uses standard HTTP response codes to display whether a method finished successfully. A two hundred response always indicates success. A four hundred type response is some sort of failure, and a five hundred type response usually indicates an internal system error.