ForHosting KIT · Images

Find the dominant color

Sometimes you don't need five colors, you need one — the color that best sums up an image before it even loads. This endpoint reduces any picture to a single representative hex value, fast enough to sit in the critical path of a page render.

● StableFree · in your browser

Run — free How it works & API

Use it from WebAPIEmailApp soonTelegram soon

The one-color question

A full palette is useful when you're building a theme or a mood board, but plenty of real interfaces only ever need to answer a much smaller question: what is the one color of this image? A background swatch behind a lazy-loading thumbnail, the fill color of a placeholder div, the accent stripe on a card — all of these want a single value, not a ranked list to pick from. Asking for a whole palette and taking the first entry works, but it's the wrong tool: this endpoint is built to answer exactly that narrower question, quickly and cheaply.

How it's computed

Send an image to POST /image/dominant-color and the task analyzes the pixel data and returns one hex value representing the color that best characterizes the image overall — not necessarily the single most frequent pixel, but the color a viewer would associate with the picture at a glance. The computation is deterministic, so repeated calls on the same image return the same result every time.

A small idea with a long track record

Reducing an image to one representative color is one of the oldest tricks in interface design, dating back to thumbnail generation on early web pages where a solid color block stood in for an image that hadn't loaded yet. What used to be a crude fallback for slow connections has become a deliberate design choice: a colored placeholder that appears instantly and transitions smoothly into the real photo feels faster than a blank box, even on a fast connection.

What you get back and when

The task runs asynchronously like everything else on this API: you receive a task_id on submission, and the single hex value comes back via signed webhook or a signed link valid for 24 hours. Because the payload is tiny — one color, not a file — it's well suited to being cached alongside an image's own metadata and reused indefinitely rather than recomputed on every page view.

How teams put it to work

The most common pattern is computing the dominant color once at upload time and storing it next to the image URL, so a gallery or feed can render an instant colored placeholder before the actual photo has downloaded, then cross-fade once it arrives. At $0.002 per request and no charge on a failed attempt, it's cheap enough to run on every image a catalog or CMS ever ingests.

What you can do with it

Instant-loading image placeholders

Store the dominant color with each image so galleries render a colored block immediately, then fade to the real photo once it loads.

Card and thumbnail backgrounds

Use the dominant color as the background fill behind a product thumbnail so odd aspect ratios never show awkward white bars.

Feed and grid theming

Tint a feed item's border or accent bar with its dominant color to give a photo grid a coherent, ambient look without manual styling.

Fast image tagging at scale

Bucket large photo libraries by a single dominant hue for quick browsing or moderation triage, without running a full palette extraction on every file.

FAQ

What's the difference between dominant color and a color palette?

Dominant color returns one hex value that best represents the whole image; the palette endpoint returns several ranked swatches when you need more than one color.

Is the dominant color API free to use?

The tool above runs free in your browser. The API is paid — each call draws from your prepaid ForHosting KIT balance: top up from $10.00 (it never expires), pay each request's published price, and a call with no balance returns HTTP 402. No subscription, no tokens, and a failed task is never charged.

Is the result always the same for a given image?

Yes, the computation is deterministic, so the same image always returns the same dominant color value.

What format is the color returned in?

A single hex color value, ready to use directly as a CSS background or fill color.

Can I process a large photo library in bulk?

Yes, each image is submitted and billed as its own request, so you can run this across an entire library without special batch endpoints.

How do I receive the dominant color result?

Via a signed webhook, recommended for automated pipelines, or a signed link valid for 24 hours.

Is the dominant color always the most frequent pixel?

Not necessarily; the computation aims for the color that best characterizes the image overall, which is usually more useful than the raw most-frequent pixel.

Should I use this for a blurred placeholder instead?

If you want a placeholder that hints at the image's shape rather than a flat swatch, the BlurHash endpoint is the better fit.

For developers — API access

Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.

API endpoint

POSThttps://api.kit.forhosting.com/image/dominant-color

Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, and soon from our app, email and Telegram.

Call it from your stack

curl -X POST https://api.kit.forhosting.com/image/dominant-color \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d &#39;{"image":"https://ejemplo.com/imagen.jpg"}'

const res = await fetch("https://api.kit.forhosting.com/image/dominant-color", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "image": "https://ejemplo.com/imagen.jpg"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/image/dominant-color",
    headers={"Authorization": f"Bearer {os.environ[&#39;KIT_KEY']}"},
    json={
    "image": "https://ejemplo.com/imagen.jpg"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/image/dominant-color", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => &#39;{"image":"https://ejemplo.com/imagen.jpg"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"image":"https://ejemplo.com/imagen.jpg"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/image/dominant-color", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Example request

{
  "image": "https://ejemplo.com/imagen.jpg"
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "image.dominant_color",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.

Pricing

Per request$0.002

Published price — no tokens, no invented credits. A failed task is never charged.

Limits

`max_mb`	15
`max_megapixels`	12

Errors

HTTP	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`402`	`insufficient_balance`	Your balance doesn't cover the task price.
`404`	`unknown_type`	That task type doesn't exist.
`429`	`rate_limited`	Too many requests. Use the webhook instead of polling.

Read the full KIT documentation →

Run — free