API Documentation

Integrate with your tools fast, with our simple, powerful color API
Upload any image to identify colors, create color palettes, and get accurate HEX, RGB, HSL, and CMYK color codes through our powerful API.

API Overview

The Color Identifier API enables programmatic extraction of dominant colors from any provided image URL. It delivers clean, reliable color palettes in multiple formats, with optional metadata for each color, including standardized names, luminance, and contrast recommendations. This functionality supports development of search features, content classification, adaptive theming, and personalization workflows.

API Endpoint

GET https://coloridentifier.org/v/api/color-identifier-api.php

Required Parameters

image (string) — The URL of the image to analyze. This parameter is mandatory and must be a publicly accessible resource.

Optional Parameters

count (int) — Number of dominant colors to return. Default is 1. Maximum is 256.

format (string) — Format of the color output. Options are:

array — Default. RGB array [r, g, b].
rgb — String format “rgb(r,g,b)”.
rgba — String format with alpha “rgba(r,g,b,1)”.
hex — Hexadecimal string “#rrggbb”.

lang (string) — ISO 639-1 language code for the color name translation. Use all to return all supported translations.

pretty (bool) — If true, returns formatted JSON for human readability.

x, y, w, h (int) — Optional cropping parameters specifying the rectangle to analyze within the image (top-left x/y and width/height in pixels).

Response Format

The response is a JSON object containing an array of detected colors with associated metadata. Each color entry includes:

rgb — Color value in requested format.
hex — Hexadecimal color code.
name — Standardized color name in requested languages.
hsl — HSL array [h, s, l].
hsv — HSV array [h, s, v].
cmyk — CMYK array [c, m, y, k].
luminance — Float value indicating perceived brightness.
yiq — Integer YIQ encoding for contrast calculations.
contrast_text — Recommended text color (“black” or “white”) over this background.
weight — Relative weight of the color in the image (percentage basis).

Example Request

GET https://coloridentifier.org/v/api/color-identifier-api.php?image=https://slash5.seanobrien.com.au/wp-content/uploads/windsurfing-great-barrier-reef-sean-obrien-aus120-21.jpg&count=3&format=hex&lang=all&pretty=true

Example Response

{
    "colors": [
        {
            "rgb": "#18beae",
            "hex": "#18beae",
            "name": {
                "en": "Light Sea Green",
                "es": "Verde mar claro",
                "fr": "Vert mer clair",
                "de": "Helles Meergrün",
                "it": "Verde mare chiaro",
                "pt": "Verde Mar Claro",
                "ua": "Світло-морська зелена",
                "ja": "ライトシーグリーン",
                "zh": "浅海绿色",
                "ar": "أخضر البحر الفاتح"
            },
            "hsl": [174, 78, 42],
            "hsv": [174, 87, 75],
            "cmyk": [87, 0, 8, 25],
            "luminance": 0.6022,
            "yiq": 139,
            "contrast_text": "black",
            "weight": 100
        },
        {
            "rgb": "#b6b6b7",
            "hex": "#b6b6b7",
            "name": {
                "en": "Silver",
                "es": "Plata",
                "fr": "Argent",
                "de": "Silber",
                "it": "Argento",
                "pt": "Prata",
                "ua": "Срібний",
                "ja": "シルバー",
                "zh": "银色",
                "ar": "فضي"
            },
            "hsl": [240, 1, 72],
            "hsv": [240, 1, 72],
            "cmyk": [1, 1, 0, 28],
            "luminance": 0.714,
            "yiq": 182,
            "contrast_text": "black",
            "weight": 66.67
        },
        {
            "rgb": "#571923",
            "hex": "#571923",
            "name": {
                "en": "Maroon",
                "es": "Marrón oscuro",
                "fr": "Marron",
                "de": "kastanienbraun",
                "it": "Marrone scuro",
                "pt": "Bordô",
                "ua": "Бордовий",
                "ja": "マルーン",
                "zh": "栗色",
                "ar": "بني محمر"
            },
            "hsl": [350, 55, 22],
            "hsv": [350, 71, 34],
            "cmyk": [0, 71, 60, 66],
            "luminance": 0.1526,
            "yiq": 45,
            "contrast_text": "white",
            "weight": 33.33
        }
    ]
}

Integrate in Your Language.

Our Color Identifier API integrates with RapidAPI, making it easy to connect and start using in your preferred development environment. Through RapidAPI, you can access ready-made code snippets for Python, JavaScript, Go, PHP, and other languages. The API accepts an image input and returns structured color data, including HEX, RGB, HSL, and CMYK representations, multilingual color names, and recommended text contrast. This enables fast integration into design tools, content workflows, or batch processing pipelines. Refer to the documentation for instructions on authentication, request formatting, and response handling.

import http.client

conn = http.client.HTTPSConnection("color-identifier.p.rapidapi.com")

headers = {
    'x-rapidapi-key': "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    'x-rapidapi-host': "color-identifier.p.rapidapi.com"
}

conn.request("GET", "/color-identifier-api.php?image=https://slash1.coloridentifier.org/wp-content/uploads/color-identifier-tool-colorful-mushrooms.jpg&count=3&format=hex%2C%20rgb&lang=en&pretty=true&x=0&y=0&w=300&h=200", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require('https');

const options = {
	method: 'GET',
	hostname: 'color-identifier.p.rapidapi.com',
	port: null,
	path: '/color-identifier-api.php?image=https%3A%2F%2Fslash1.coloridentifier.org%2Fwp-content%2Fuploads%2Fcolor-identifier-tool-colorful-mushrooms.jpg&count=3&format=hex%2C%20rgb&lang=en&pretty=true&x=0&y=0&w=300&h=200',
	headers: {
		'x-rapidapi-key': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
		'x-rapidapi-host': 'color-identifier.p.rapidapi.com'
	}
};

const req = http.request(options, function (res) {
	const chunks = [];

	res.on('data', function (chunk) {
		chunks.push(chunk);
	});

	res.on('end', function () {
		const body = Buffer.concat(chunks);
		console.log(body.toString());
	});
});

req.end();

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener('readystatechange', function () {
	if (this.readyState === this.DONE) {
		console.log(this.responseText);
	}
});

xhr.open('GET', 'https://color-identifier.p.rapidapi.com/color-identifier-api.php?image=https%3A%2F%2Fslash1.coloridentifier.org%2Fwp-content%2Fuploads%2Fcolor-identifier-tool-colorful-mushrooms.jpg&count=3&format=hex%2C%20rgb&lang=en&pretty=true&x=0&y=0&w=300&h=200');
xhr.setRequestHeader('x-rapidapi-key', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
xhr.setRequestHeader('x-rapidapi-host', 'color-identifier.p.rapidapi.com');

xhr.send(data);

 "https://color-identifier.p.rapidapi.com/color-identifier-api.php?image=https%3A%2F%2Fslash1.coloridentifier.org%2Fwp-content%2Fuploads%2Fcolor-identifier-tool-colorful-mushrooms.jpg&count=3&format=hex%2C%20rgb&lang=en&pretty=true&x=0&y=0&w=300&h=200",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_ENCODING => "",
	CURLOPT_MAXREDIRS => 10,
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "GET",
	CURLOPT_HTTPHEADER => [
		"x-rapidapi-host: color-identifier.p.rapidapi.com",
		"x-rapidapi-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
	],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
	echo "cURL Error #:" . $err;
} else {
	echo $response;
}

curl -X GET "https://color-identifier.p.rapidapi.com/color-identifier-api.php?image=https%3A%2F%2Fslash1.coloridentifier.org%2Fwp-content%2Fuploads%2Fcolor-identifier-tool-colorful-mushrooms.jpg&count=3&format=hex%2C%20rgb&lang=en&pretty=true&x=0&y=0&w=300&h=200" \
  -H "x-rapidapi-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "x-rapidapi-host: color-identifier.p.rapidapi.com"

import http.client

conn = http.client.HTTPSConnection("color-identifier.p.rapidapi.com")

headers = {
    'x-rapidapi-key': "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    'x-rapidapi-host': "color-identifier.p.rapidapi.com"
}

conn.request("GET", "/color-identifier-api.php?image=https://slash1.coloridentifier.org/wp-content/uploads/color-identifier-tool-colorful-mushrooms.jpg&count=3&format=hex%2C%20rgb&lang=en&pretty=true&x=0&y=0&w=300&h=200", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))