Image Extraction: Colors, Metadata & Favicon

Extract intelligence from images without downloading or processing them locally. The Image Toolkit provides endpoints for dominant colour extraction, EXIF/metadata analysis, and favicon discovery — all accessible via either POST (base64 or URL input) or GET (URL-query) methods.

Base URL

https://image.toolkitapi.io

Endpoints

Method Endpoint Input Description
POST /v1/image/extract/colors base64 or URL Extract dominant colour palette
GET /v1/image/extract/colors URL only Extract dominant colour palette
POST /v1/image/extract/metadata base64 or URL Extract EXIF metadata & dimensions
GET /v1/image/extract/metadata URL only Extract EXIF metadata & dimensions
GET /v1/image/favicon domain/URL Fetch highest-resolution favicon

1. Colour Palette Extraction

Extract the N most dominant colours from an image as hex codes and RGB values. Uses ColorThief or PIL fallback.

# POST with URL
curl -X POST "https://image.toolkitapi.io/v1/image/extract/colors" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "count": 6}'

# GET with URL (simpler for quick checks)
curl "https://image.toolkitapi.io/v1/image/extract/colors?url=https://example.com/photo.jpg&count=6" \
  -H "X-API-Key: YOUR_KEY"
import requests

# POST with URL
resp = requests.post(
    "https://image.toolkitapi.io/v1/image/extract/colors",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"url": "https://example.com/photo.jpg", "count": 8},
)
data = resp.json()
for c in data["colors"]:
    print(f"  {c['hex']}  RGB({c['rgb']['r']}, {c['rgb']['g']}, {c['rgb']['b']})")

# POST with local file (base64)
import base64
with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/extract/colors",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"image": b64, "count": 5},
)
print(resp.json()["colors"])
// POST with URL
const resp = await fetch("https://image.toolkitapi.io/v1/image/extract/colors", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/photo.jpg", count: 6 }),
});
const data = await resp.json();
data.colors.forEach(c => console.log(`${c.hex} (${c.rgb.r},${c.rgb.g},${c.rgb.b})`));

Request Parameters (POST)

Parameter Type Required Default Description
image string No* — Base64-encoded image data (PNG/JPEG/WebP)
url string No* — Public image URL
count integer No 6 Number of dominant colours (1–20)

* Exactly one of image or url must be provided.

GET Query Parameters

Parameter Type Required Default Description
url string Yes — Public image URL
count integer No 6 Number of dominant colours (1–20)

Response Fields

Field Type Description
colors array [{ hex, rgb: { r, g, b } }] sorted by dominance
count integer Number of colours returned
image_size object { width, height } of the source image

Use case: Brand colour extraction

import requests

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/extract/colors",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"url": "https://toolkitapi.io/logo.png", "count": 3},
)
brand_colors = [c["hex"] for c in resp.json()["colors"]]
# ['#2563eb', '#1d4ed8', '#1e40af']

2. Image Metadata Extraction

Extract image properties — dimensions, format, colour mode, EXIF tags, animation info, and file size.

# POST with URL
curl -X POST "https://image.toolkitapi.io/v1/image/extract/metadata" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

# GET shortcut
curl "https://image.toolkitapi.io/v1/image/extract/metadata?url=https://example.com/photo.jpg" \
  -H "X-API-Key: YOUR_KEY"
import requests

resp = requests.get(
    "https://image.toolkitapi.io/v1/image/extract/metadata",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"url": "https://example.com/photo.jpg"},
)
meta = resp.json()
print(f"Format: {meta['format']}")
print(f"Size: {meta['size']['width']}x{meta['size']['height']}")
print(f"Megapixels: {meta['megapixels']}")
print(f"Colour mode: {meta['mode']}")
print(f"Has alpha: {meta['has_alpha']}")
print(f"EXIF fields: {len(meta.get('exif', {}))}")
if "exif" in meta:
    print(f"Camera: {meta['exif'].get('Model', 'N/A')}")
const resp = await fetch(
  "https://image.toolkitapi.io/v1/image/extract/metadata?url=https://example.com/photo.jpg",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const meta = await resp.json();
console.log(`${meta.size.width}x${meta.size.height}, ${meta.format}`);

Response Fields

Field Type Description
format string Image format (jpeg, png, webp, gif, etc.)
mode string PIL colour mode (RGB, RGBA, L, etc.)
size object { width, height }
megapixels number Width × height in megapixels
file_size_bytes integer Raw file size
has_alpha boolean Whether the image has an alpha channel
is_animated boolean Whether the image is animated (GIF, WebP, PNG)
frames integer Number of frames (animated images)
exif object EXIF metadata key-value pairs (if present)

Use case: Validate image before processing

import requests

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/extract/metadata",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"url": "https://example.com/upload.jpg"},
)
meta = resp.json()

# Check minimum requirements
if meta["size"]["width"] < 800 or meta["size"]["height"] < 600:
    print("Image too small — needs at least 800x600")
if meta["file_size_bytes"] > 10 * 1024 * 1024:
    print("Image too large — exceeding 10 MB")
if meta["format"] not in ("jpeg", "png", "webp"):
    print("Unsupported format")

3. Favicon Fetcher

Fetch the highest-resolution favicon for any domain. Checks multiple sources in priority order:

  1. Apple touch icon (/apple-touch-icon.png)
  2. Standard /favicon.ico
  3. HTML <link rel="icon"> tags
  4. Google favicon service fallback
curl "https://image.toolkitapi.io/v1/image/favicon?domain=github.com" \
  -H "X-API-Key: YOUR_KEY"
import base64
import requests

resp = requests.get(
    "https://image.toolkitapi.io/v1/image/favicon",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"domain": "github.com"},
)
data = resp.json()
best = data["favicon"]
print(f"Source: {best['source']}")
print(f"URL: {best['url']}")
print(f"Size: {best['size_bytes']} bytes")

# Save to file
with open("favicon.png", "wb") as f:
    f.write(base64.b64decode(best["data"]))
const resp = await fetch(
  "https://image.toolkitapi.io/v1/image/favicon?domain=github.com",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(`Found ${data.all_candidates.length} candidate(s)`);
console.log(`Best: ${data.favicon.url} (${data.favicon.size_bytes} bytes)`);

Request Parameters

Parameter Type Required Description
domain string Yes Domain name or full URL to fetch favicon for

Response Fields

Field Type Description
domain string Normalised domain
favicon object The best candidate found
favicon.url string Source URL of the favicon
favicon.source string How it was found: apple-touch-icon, favicon.ico, html-link, or google-fallback
favicon.content_type string MIME type
favicon.data string Base64-encoded favicon data
favicon.size_bytes integer File size
all_candidates array All discovered favicon URLs with source and size metadata

Error Handling

HTTP Status Meaning
200 Success
400 Invalid image data, unsupported format, or missing required parameter
404 No favicon found for the domain
500 Internal processing error (e.g. colour extraction or metadata parsing failure)

Common issues: - POST with neither image nor url: Provide exactly one. - Empty or corrupt base64: Ensure the base64 string is valid and uncorrupted. - Large images: Images up to 20 MB are supported via URL fetch. Larger files may timeout. - Unsupported formats: For colour extraction, non-RGB images are converted internally. Some extremely niche formats may fail.


Tips

  • Choose the right method: Use POST when you have base64 data from client uploads. Use GET for Zapier or simple URL-based workflows.
  • Colour count: For branding/design use cases, 3–6 colours work well. For data analysis, up to 20 colours gives finer granularity.
  • Metadata validation: Always check is_animated before processing GIFs/WebPs frame-by-frame.
  • Favicon quality: The endpoint always returns the largest candidate by byte size, which correlates with highest resolution. Check all_candidates if you need a specific format.
  • EXIF privacy: Metadata extraction exposes GPS and camera info. Use this to audit user uploads for privacy compliance.