Image Processing API

Image Processing API performs image processing and returns processing results. This guide demonstrates the basic usage of Image Processing API.

Contents

• Quick Start
• Endpoints
• How to Filter an Image
• Errors
• Samples
• See Also

Quick Start

This section is designed to show you how to get started with Image Processing API. If you already have an API client for Image Processing 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 Image Processing 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 Image Processing 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 Image Processing API

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

• How to apply image filters to an image

Endpoints

This section lists all of the Image Processing API endpoints and a relevant endpoint:

Image Filtering

Image Filtering API can apply image filters to specified locations in an image. Image Filtering API returns an image after applying image filters.

Note: Even you request a png format image, this API will return jpeg format image.

Endpoint

• https://vps.api.ricoh/v1/filter

Request

Requests must include three elements:

• An image data
• 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 and parameters:

Specify an Image as Binary Data

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

Specify an Image as URL

The request body should look like this:

{
  "image": "http://vps.api.ricoh/sample.jpg",
  "parameters": {
    "locations": [
      {"left": 226, "top": 227, "right": 387, "bottom": 387}
    ],
    "type": "gaussian",
    "options": {
      "ksize_width": 3,
      "ksize_height": 3,
      "sigma_x": 0,
      "sigma_y": 0,
      "locations": {
        "shape": "min_enclosing_circle",
        "edge": "blur"
      }
    }
  }
}

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

Note: The image must meet all of the following criteria:

• The image size should be less than 4MB.

Specify Parameters

Specify options for target locations to which image filters are applied

You can specify options for the target locations. If this option is not specified, the rectangular locations specified by left, top, right, bottom become the target locations to which filters are applied.

{
  "options": {
    "locations": {
      "shape": "min_enclosing_circle",
      "edge": "blur"
    }
  }
}

Filter Types

Image Filtering API supports the following filter types:

• Blur Filter
• Gaussian Filter
• Median Filter

Each filter type has its own optional parameters to customize the behavior.

Blur Filter

Applies image filters to an image using a blur filter. All options must be a value from 1 to 100. Increasing the kernel size will result in a stronger filter processing on the image.

Gaussian Filter

Applies image filters to an image using a gaussian filter. All options must be a value from 0 to 100. ksize_width and ksize_height must be odd. If ksize_width and ksize_height are both set to zero, the kernel size is calculated from sigma_x and sigma_y. If sigma_y is zero, it is set to be equal to sigma_x. If both sigmas are zeros, they are calculated from ksize_width and ksize_height. In that case, ksize_width and ksize_height must be a value greater than 0.

Median Filter

Applies image filters to an image using a median filter. ksize must be odd and a value from 3 to 99.

Response

A successful response returns an image after applying image filters.

Example

This section demonstrates examples of Image Filtering API request with cURL and successful response. You can specify a URI of image and parameters with the --data option.

Blur multiple locations

Example Request

curl -X POST 'https://vps.api.ricoh/v1/filter' \
     --header 'Authorization: Bearer <Access Token>' \
     --header 'x-api-key: <API Key>' \
     --header 'Content-Type: application/json' \
     --data '{"image": "https://api.ricoh/demo/img/hd-002.jpg", "parameters": {"locations": [{"left": 943, "top": 276, "right": 1026, "bottom": 362}, {"left": 76, "top": 447, "right": 152, "bottom": 524}, {"left": 1189, "top": 258, "right": 1261, "bottom": 332}, {"left": 306, "top": 456, "right": 373, "bottom": 534}, {"left": 1102, "top": 349, "right": 1167, "bottom": 422}, {"left": 742, "top": 405, "right": 794, "bottom": 462}, {"left": 621, "top": 415, "right": 668, "bottom": 470}], "type": "gaussian", "options": {"ksize_width": 51, "ksize_height": 51, "sigma_x": 0, "sigma_y": 0, "locations": {shape": "min_enclosing_circle", "edge": "blur"}}}}' \
     > hd-002-human-blurred.jpg

Example Response

Here is an example of a successful response:

Difference of each filter

In this section we show an example where you can see the differences of each filter. ksize is fixed at 9.

Blur Filter

Gaussian Filter

Median Filter

Errors

Image Processing 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, Image Processing 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

• Image Processing Sample

See Also

• Image Processing API Reference
• RICOH Cloud SDK