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 |
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']
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:
- Apple touch icon (
/apple-touch-icon.png)
- Standard
/favicon.ico
- HTML
<link rel="icon"> tags
- 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.