Dominant Colors

Quickstart Test in App Public Demo

To access the Ximilar API, first register at Ximilar App to get your API token. To browse and test available solutions, select "Dominant Colors" in the app. A public demo is also available.

Given a list of image records, Dominant Colors API extracts the dominant colors from each image and returns them in formats of your choice. The response can provide color values 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. This allows for quick categorization of fashion apparel or images based on the dominant color.

Endpoints

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

https://api.ximilar.com/dom_colors/product/v2/dominantcolor  (for product images)
https://api.ximilar.com/dom_colors/generic/v2/dominantcolor  (for real-life or stock images)

POST/v2/dominantcolor

Product Dominant Colors

This endpoint is optimized for product images (e.g., fashion apparel, home decor, and pieces of furniture). It returns dominant colors with their percentages, RGB values, LUV values, color names, and Pantone names.

Required attributes

Name
records
Type
dict
Max
Maximum:10
Description
A batch of JSON records (max 10). Each record represents a single image, defined by _url or _base64.

Optional attributes

Name
colors
Type
integer
Default
Default:3
Description
The maximum number of dominant colors to be returned. For product photos, default is 3.
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. The response body 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
  }
}