Dominant Colors

Quickstart Test in APP Public Demo

This page describes API of Dominant Colors service for images. With this service you can analyze photos and extract dominant colors with their percentages, RGB values, LUV values, color names, and Pantone names. The service provides two endpoints - one optimized for product images and one for generic images.

Both endpoints return one or more dominant colors in multiple formats:

RGB number values (e.g., [241, 240, 241])
RGB hex values (e.g., "#f1f0f1")
LUV color space values
Color names according to CSS3 color standard
Pantone color names

Additionally, we provide simplified color results using just 12 basic colors: black, grey, white, red, pink, orange, yellow, green, blue, purple, brown, and beige.

Endpoints

This service API has two endpoints running at URLs, each suitable for different use cases:

https://api.ximilar.com/dom_colors/product/v2/dominantcolor  (for product images)
https://api.ximilar.com/dom_colors/generic/v2/dominantcolor  (for generic images)

POST/v2/dominantcolor

Product Dominant Colors

This endpoint is optimized for product images and returns dominant colors with their percentages, RGB values, LUV values, color names, and Pantone names.

Required attributes

Name
records
Type
dict
Description
A batch of json records (max 10), one record is representation of an image and it's defined by _url or _base64.

Optional attributes

Name
colors
Type
integer
Default
Default:3
Description
The maximum number of dominant colors to be returned. Default is 3 for product photos.
Name
_extract_object
Type
boolean
Description
When set to true along with _objects field (same structure as Custom Object Detection and Fashion Tagging), it will extract colors for the specific area of the first object.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object (map) with the following fields:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by field _dominant_colors containing color information.
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/dominantcolor

curl https://api.ximilar.com/dom_colors/product/v2/dominantcolor \
-H "Content-Type: application/json" \
-H "Authorization: Token __API_TOKEN__" \
-d '{
  "records": [
    {
      "_url": "__PATH_TO_IMAGE_URL__"
    }
  ],
  "colors": 3
}'

Response

{
  "records": [
    {
      "_url": "__IMG_URL__",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "674deba1-5c19-4c02-8bb7-6b088613e899"
      },
      "_id": "504e52fe-7d4c-4b13-a7ff-f97f36ef5d9f",
      "_width": 3679,
      "_height": 3679,
      "_dominant_colors": {
        "rgb_colors": [
          [241, 240, 241],
          [130, 131, 100],
          [191, 170, 81]
        ],
        "luv_colors": [
          [95, 0, -1],
          [54, 1, 23],
          [70, 19, 57]
        ],
        "percentages": [0.88, 0.08, 0.04],
        "rgb_hex_colors": [
          "#f1f0f1",
          "#828364",
          "#bfaa51"
        ],
        "color_names": [
          "whitesmoke",
          "darkolivegreen",
          "darkkhaki"
        ],
        "color_names_pantone": [
          "Blanc De Blanc",
          "Oil Green",
          "Cress Green"
        ],
        "color_names_simple": {
          "white": 0.88,
          "green": 0.12
        }
      }
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "674deba1-5c19-4c02-8bb7-6b088613e899",
    "proc_id": "d91ef2bb-6dfe-4362-b552-b8aed91c0761"
  },
  "statistics": {
    "processing time": 7.062758207321167
  }
}