Visual Recognition API

Visual Recognition API detects and recognizes people and human faces in images. The API supports three functions:

• Human Detection - Detects human heads in an image.
• Face Detection - Detects human faces in an image.
• Face Recognition - Compares faces in images or collection to enable developers to identify people.

This guide demonstrates the basic usage of Visual Recognition API.

Contents

• Quick Start
• Endpoints
• How to Detect Humans
• How to Detect Faces
• How to Recognize Faces
• Errors
• Samples
• See Also

Quick Start

This section is designed to show you how to get started with Visual Recognition API. If you already have an API client for Visual Recognition API, you can skip Step 1. Note that you need a RICOH Account for Step 1. To create one, see Get Started for detailed instructions.

Step 1: Create an API Client

Create an API client for Visual Recognition API at Management Console. See Get Started for detailed instructions. After you successfully finish the procedure, you can check your Client ID and Client Secret at Dashboard.

Step 2: Obtain an Access Token

Obtain an access token using your Client ID and Client Secret to authenticate your API requests. Notice that Visual Recognition API supports Client Credentials Grant of Authorization API. Learn how to make a request to Authorization API to obtain an access token and an API key at Obtain an Access Token and implement it to your application.

Step 3: Try Visual Recognition API

Try Visual Recognition API using your access token and API key. See the following sections of individual APIs for brief explanation and request examples.

• How to Detect Humans
• How to Detect Faces
• How to Recognize Faces

Endpoints

This section lists all of the Visual Recognition API endpoints and a relevant endpoint:

Human Detection

Human Detection detects human heads in images. It can detect human heads even when you can see only their backside. Human Detection returns position information for the detected faces.

Endpoint

Request

Requests must include three elements:

• An image to request
• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

You can specify the image in one of two ways:

Specify Image as Binary Data

The data should be stored in the request body. The request should include the Content-Type header with the value of either image/jpeg or image/png.

Specify Image as URL

The request body should look like this:

{
  "image": "http://ips.api.ricoh/sample.jpg"
}

The request should include the Content-Type header with the value of application/json.

Note:
Images must meet all of the following criteria:

• Image size should be less than 4MB.

Response

A successful response returns an array of detected human heads in JSON. A detected head is described with location (a rectangular-shaped detection area in the image) and score (detection confidence). The score can be from 0.1 to 1, as 1 the highest.

Example

This section demonstrates an example Human Detection request with cURL, and its example response.

Example Request

Here is an example of sending a Human Detection request with sample.jpeg using cURL. You can specify sample.jpeg with the --data-binary option.

curl -X POST 'https://ips.api.ricoh/v1/detect_humans' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API Key>' \
     --header 'Content-Type: image/jpeg' \
     --data-binary '@sample.jpeg'

Example Response

Here is an example of a successful response:

{
  "humans": [
    {
      "score": 0.921,
      "location": {
        "left": 658,
        "top": 130,
        "right": 874,
        "bottom": 310
      }
    }
  ]
}

Face Detection

Face Detection detects human faces in images. It returns positions of detected faces in the image as well as the directions which they face.

Endpoint

Request

You can create requests in the same way as Human Detection. See Human Detection’s Request for details.

Response

A successful response returns an array of detected faces in JSON. A detected face is described with location (a rectangular-shaped detection area in the image) and direction (the direction which the face looks in). The direction can be either front, left, or right.

Example

This section demonstrates an example Face Detection request with cURL, and its example response.

Example Request

Here is an example of sending a Face Detection request with sample.jpeg using cURL. You can specify sample.jpeg with the --data-binary option.

curl -X POST 'https://ips.api.ricoh/v1/detect_faces' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: image/jpeg' \
     --data-binary '@sample.jpeg'

Example Response

Here is an example of a successful response:

{
  "faces": [
    {
      "direction": "front",
      "location": {
        "left": 658,
        "top": 130,
        "right": 874,
        "bottom": 310
      }
    }
  ]
}

Face Recognition

Face Recognition enables developers to identify people by returning how similar the faces are. The following two APIs are prepared to calculate similarity.

The first API is Compares faces in two images.This API detects faces in two images and returns the similarity of those faces. This API is easier to start than another API.

The second API is Compares faces to collection. This API allows you to compare up to 1000 faces with a single request. It is necessary to prepare a face collection and add a face, but it is better to use a face collection for use cases where you want to repeatedly calculate a large amount of similarity.

Compares faces in two images

Detects faces from each of the specified two images and returns the similarity of those faces. If this API detects more than two faces in a requested image, the face detected with more confidence is used for comparison.

Note:
Images must meet all of the following criteria:

• Image size: Less than 4MB in total
• Face size: From 120x120 pixels to 280x280 pixels

Endpoint

Request

Requests must include three elements:

• Two images to request
• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

You can specify the images in one of two ways:

Specify Images as Binary Data

The images should be either jpeg or png. The request should include the Content-Type header with the value of multipart/form-data.

Specify Images as URL

The request body should look like this:

{
  "source": "http://ips.api.ricoh/sample1.jpg",
  "target": "http://ips.api.ricoh/sample2.jpg"
}

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns two detected faces and score (comparison result) in JSON. A detected face is described with location (a rectangular-shaped detection area in the image). The score is a number ranging from 0 to 1. The higher the score, the more identical the detected faces are.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to compares faces in two images using cURL. You can specify two images (sample1.jpeg and sample2.jpeg) with the --form options.

curl -X POST 'https://ips.api.ricoh/v1/compare_faces' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: multipart/form-data' \
     --form 'source=@sample1.jpeg' \
     --form 'target=@sample2.jpeg'

Example Response

Here is an example of a successful response:

{
  "score": 0.9067732095718384,
  "source": {
    "location": {
      "left": 658,
      "top": 130,
      "right": 874,
      "bottom": 310
    }
  },
  "target": {
    "location": {
      "left": 658,
      "top": 130,
      "right": 874,
      "bottom": 310
    }
  }
}

Compares faces to collection

Detects face from the image and returns the similarity with all faces in the face collection. If this API detects more than one face in a requested image, the face detected with more confidence is used for comparison. The criterion of the image is the same as Compares faces in two images. It is necessary to prepare face collection in advance. See Creates collection and Adds face to collection for details.

Endpoint

Request

Requests must include three elements:

• An image, collection_id to request
• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

Optional parameter:

• max_results The number of top similar faces returned. You can specify a number from 1 to 1000. The default is 10.

You can specify the image in one of two ways:

Specify Images as Binary Data

The images should be either jpeg or png. The request should include the Content-Type header with the value of multipart/form-data.

Specify Images as URL

The request body should look like this:

{
  "image": "http://ips.api.ricoh/sample1.jpg"
}

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns detected face and score (comparison result) in JSON. A detected face is described with location (a rectangular-shaped detection area in the image). The score is a number ranging from 0 to 1. The higher the score, the more identical the detected faces are. A score of all faces of the specified face collection is described in the faces array.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to compares faces to collection using cURL. You can specify image (sample1.jpeg) with the --form options and collection_id with the path parameters.

curl -X POST 'https://ips.api.ricoh/v1/compare_faces/7446b55e-3f52-43ea-9b79-cecd5a848770' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: multipart/form-data' \
     --form 'image=@sample.jpeg' \
     --form 'max_results=3'

Example Response

Here is an example of a successful response:

{
  "source": {
    "location": {
      "left": 658,
      "top": 130,
      "right": 874,
      "bottom": 310
    }
  },
  "target": {
    "collection_id" : "7446b55e-3f52-43ea-9b79-cecd5a848770",
    "faces": [
        {
           "face_id": "b3a22f9f-096c-4c82-b7a1-9e9ac14e77b3",
           "score": "0.93479879182737221"
        },
        {
           "face_id": "369fd2fa-9109-4a59-9930-1cee13e4726f",
           "score": "0.62898903479871247"
        },
        {
           "face_id": "c69500a2-a110-42c5-a1e7-db8411c3179e",
           "score": "0.44163933396339417"
        }
    ]
  }
}

Creates collection

Create an empty face collection. A face collection is a collection of faces. Up to 1000 faces can be added in a face collection. See Adds face to collection for details.

Note:
The following restrictions apply during the beta period.

• The number of face collections that can be created is one for client ID / client secret pairs.
• The created face collection may be deleted without notice.

Endpoint

Request

Requests must include two elements:

• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

The request should include the Content-Type header with the value of application/json.

Response

If the response is successful, collection_id will be returned.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to create a collection using cURL.

curl -X POST 'https://ips.api.ricoh/v1/face_collections' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: application/json'

Example Response

Here is an example of a successful response:

{
  "collection_id": "19e9cdf-ea91-4854-8f7f-7477b7c71820"
}

Adds face to collection

Detects face from a image and add it in the face collection. Up to 1000 faces can be added in a face collection. If this API detects more than one face in a requested image, the face detected with more confidence is used for adding. The criterion of the image is the same as Compares faces in two images.

Endpoint

Request

Requests must include three elements:

• An image to request
• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

You can specify the image in one of two ways:

Specify Images as Binary Data

The images should be either jpeg or png. The request should include the Content-Type header with the value of multipart/form-data.

Specify Images as URL

The request body should look like this:

{
  "image": "http://ips.api.ricoh/sample1.jpg"
}

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns face_id and location in JSON. face_id is the id that the API automatically assigned. A detected face is described with location (a rectangular-shaped detection area in the image).

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to add a face to a collection using cURL. You can specify image (sample1.jpeg) with the --form options.

curl -X POST 'https://ips.api.ricoh/v1/face_collections/7446b55e-3f52-43ea-9b79-cecd5a848770/faces' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: multipart/form-data' \
     --form 'image=@sample1.jpeg' \

Example Response

Here is an example of a successful response:

{
  "face_id": "9c212a4f-a90c-4a6c-ad13-26479124b583",
  "location": {
    "left": 3628,
    "top": 825,
    "right": 4339,
    "bottom": 1526
  }
}

Lists collections

Returns a list of face collections.

Endpoint

Request

Requests must include two elements:

• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns a list of face collection in JSON.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to list collections using cURL.

curl 'https://ips.api.ricoh/v1/face_collections' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: application/json'

Example Response

Here is an example of a successful response:

{
  "face_collections": [
    {
      "collection_id": "19e9cdf-ea91-4854-8f7f-7477b7c71820"
    }
  ]
}

Lists faces from collection

Return a list of faces stored in the face collection.

Endpoint

Request

Requests must include two elements:

• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns a list of faces from the face collection.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to list a collections faces using cURL.

curl 'https://ips.api.ricoh/v1/face_collections/7446b55e-3f52-43ea-9b79-cecd5a848770/faces' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: application/json'

Example Response

Here is an example of a successful response:

{
  "faces": [
    {
      "face_id": "9d68c581-dc13-4d10-b631-0ee7ec1598c5"
    }
  ]
}

Deletes collection

Delete a face collection. If you delete a face collection, all stored faces will also be deleted and cannot be referred. Please note that you can not restore the deleted face collection (and the added face).

Endpoint

Request

Requests must include two elements:

• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns an empty body.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to delete a collection using cURL.

curl -X DELETE 'https://ips.api.ricoh/v1/face_collections/7446b55e-3f52-43ea-9b79-cecd5a848770' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: application/json'

Example Response

Here is an example of a successful response. response body is empty.

Removes face from collection

Remove a face in a face collection. If you remove a face, you can not be referred. Please note that you can not restore the face once removed.

Endpoint

Request

Requests must include two elements:

• Authorization header with the access token you’ve obtained
• x-api-key header with the API key you’ve obtained

The request should include the Content-Type header with the value of application/json.

Response

A successful response returns an empty body.

Example

This section demonstrates an example request with cURL, and its example response.

Example Request

Here is an example of sending a request to remove a face using cURL.

curl -X POST 'https://ips.api.ricoh/v1/face_collections/7446b55e-3f52-43ea-9b79-cecd5a848770/faces/9d68c581-dc13-4d10-b631-0ee7ec1598c5' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API key>' \
     --header 'Content-Type: application/json'

Example Response

Here is an example of a successful response. response body is empty.

Errors

Visual Recognition API supports errors in Common Errors and its own errors described in the following table.

When one of the errors described below occurs, you might receive an error response with a JSON formatted body and it looks like this:

{
  "message": "<string>"
}

There is an exception of response body format. When you request an image larger than 10MB, you receive an error response with a text formatted body along with status code 413. The body looks like this:

HTTP content length exceeded 10485760 bytes.

Note:
Unlike Common Errors, Visual Recognition API errors do NOT contain code field. Error causes are described in message field.

Error Codes

The following table shows the errors you might encounter only when you use Visual Recognition API.

Samples

• Visual Recognition Sample

See Also

• Visual Recognition API Reference
• RICOH Cloud SDK