Extraction and Conversion¶
Image intelligence and format conversion — extract metadata, detect dominant colours, fetch favicons, and convert between formats.
Endpoints¶
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/image/extract/metadata |
Read EXIF and other metadata from a base64 image |
GET |
/v1/image/extract/metadata |
Read metadata from an image URL |
POST |
/v1/image/extract/colors |
Extract dominant colours from a base64 image |
GET |
/v1/image/extract/colors |
Extract colours from an image URL |
GET |
/v1/image/favicon |
Fetch the highest-resolution favicon for a domain |
POST |
/v1/image/convert |
Convert and return JSON with base64 in result |
GET |
/v1/image/convert |
Convert and stream a file |
GET |
/v1/image/download/{object_name} |
Download a previously processed image |
Examples¶
Extract image metadata (EXIF)¶
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",
params={"url": "https://example.com/photo.jpg"},
headers={"X-API-Key": "YOUR_KEY"},
)
data = resp.json()
# EXIF data if available
if data.get("exif"):
print(f"Camera: {data['exif'].get('Make', 'Unknown')} {data['exif'].get('Model', '')}")
print(f"Taken: {data['exif'].get('DateTimeOriginal')}")
print(f"GPS: {data['exif'].get('GPSInfo', 'Not available')}")
# Basic properties
print(f"Format: {data['format']}, Size: {data['size']['width']}x{data['size']['height']}")
print(f"Mode: {data['mode']}, {data['megapixels']} MP, alpha={data['has_alpha']}")
print(f"File size: {data['file_size_bytes']} bytes")
const params = new URLSearchParams({ url: "https://example.com/photo.jpg" });
const resp = await fetch(
`https://image.toolkitapi.io/v1/image/extract/metadata?${params}`,
{ headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(`${data.format} ${data.width}x${data.height}, ${data.file_size_bytes} bytes`);
Response
{
"format": "JPEG",
"width": 4032,
"height": 3024,
"file_size_bytes": 2456789,
"exif": {
"Make": "Apple",
"Model": "iPhone 15 Pro",
"DateTimeOriginal": "2024-06-15T14:30:00",
"GPSInfo": {"latitude": 37.7749, "longitude": -122.4194}
}
}
Extract dominant colours¶
curl "https://image.toolkitapi.io/v1/image/extract/colors?url=https://example.com/brand.jpg" \
-H "X-API-Key: YOUR_KEY"
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/extract/colors",
params={"url": "https://example.com/brand.jpg"},
headers={"X-API-Key": "YOUR_KEY"},
)
data = resp.json()
for color in data["colors"][:5]:
print(f" {color['hex']} — {color['percentage']}% ({color['name']})")
const params = new URLSearchParams({ url: "https://example.com/brand.jpg" });
const resp = await fetch(
`https://image.toolkitapi.io/v1/image/extract/colors?${params}`,
{ headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
data.colors.forEach(c => console.log(`${c.hex} (${c.percentage}%)`));
Response
{
"url": "https://example.com/brand.jpg",
"colors": [
{"hex": "#FF5733", "name": "Persimmon", "percentage": 42.5, "rgb": [255, 87, 51]},
{"hex": "#FFFFFF", "name": "White", "percentage": 28.3, "rgb": [255, 255, 255]},
{"hex": "#333333", "name": "Dark Gray", "percentage": 15.1, "rgb": [51, 51, 51]}
],
"query_time_ms": 245.6
}
Fetch a favicon¶
curl "https://image.toolkitapi.io/v1/image/favicon?domain=github.com" \
-H "X-API-Key: YOUR_KEY"
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/favicon",
params={"domain": "github.com"},
headers={"X-API-Key": "YOUR_KEY"},
)
data = resp.json()
fav = data["favicon"]
print(f"Favicon: {fav['url']} ({fav['source']}, {fav['size_bytes']} bytes)")
for c in data["all_candidates"]:
print(f" candidate: {c['source']} -> {c['url']}")
const params = new URLSearchParams({ domain: "github.com" });
const resp = await fetch(
`https://image.toolkitapi.io/v1/image/favicon?${params}`,
{ headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(`Favicon: ${data.favicon.url} (${data.favicon.source}, ${data.favicon.size_bytes} bytes)`);
Response
{
"domain": "github.com",
"favicon": {
"url": "https://github.com/apple-touch-icon.png",
"source": "apple-touch-icon",
"content_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUg...",
"size_bytes": 8421
},
"all_candidates": [
{ "url": "https://github.com/apple-touch-icon.png", "source": "apple-touch-icon", "size_bytes": 8421 },
{ "url": "https://github.com/favicon.ico", "source": "favicon.ico", "size_bytes": 1150 }
]
}
Response shape
The favicon is nested under favicon, and its fields are url, source, content_type, data (base64), and size_bytes. There are no top-level favicon_url, width, or height fields — the service picks the highest-resolution candidate by file size rather than reporting pixel dimensions.
Sources are tried in priority order: Apple touch icon, then /favicon.ico, then <link rel="icon"> tags scraped from the page, then the Google favicon service as a fallback.
Convert image format¶
# POST variant returns JSON with base64 in the `result` field
curl -X POST "https://image.toolkitapi.io/v1/image/convert" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/photo.jpg", "from_format": "jpeg", "to_format": "webp", "quality": 85}'
import base64
import requests
resp = requests.post(
"https://image.toolkitapi.io/v1/image/convert",
headers={"X-API-Key": "YOUR_KEY"},
json={
"url": "https://example.com/photo.jpg",
"from_format": "jpeg", # source format is required
"to_format": "webp", # target format is required
"quality": 85,
},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
with open("converted.webp", "wb") as f:
f.write(base64.b64decode(data["result"]))
print(f"Converted {data['from_format']} → {data['to_format']}: {data['file_size_bytes']} bytes")
const resp = await fetch("https://image.toolkitapi.io/v1/image/convert", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
url: "https://example.com/photo.jpg",
from_format: "jpeg",
to_format: "webp",
quality: 85,
}),
});
const data = await resp.json();
console.log(`Converted ${data.from_format} → ${data.to_format} (${data.width}x${data.height})`);
Response
{
"success": true,
"from_format": "jpeg",
"to_format": "webp",
"result": "UklGRiQAAABXRUJQ...",
"content_type": "image/webp",
"file_size_bytes": 41288,
"width": 1920,
"height": 1080,
"data_uri": "data:image/webp;base64,UklGRiQAAABXRUJQ..."
}
Convert and stream the file (GET)¶
The GET variant returns the converted bytes directly — no base64 decoding needed.
curl -G "https://image.toolkitapi.io/v1/image/convert" \
-H "X-API-Key: YOUR_KEY" \
--data-urlencode "url=https://example.com/photo.jpg" \
--data-urlencode "from_format=jpeg" \
--data-urlencode "to_format=png" \
--data-urlencode "quality=90" \
--output converted.png
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/convert",
params={
"url": "https://example.com/photo.jpg",
"from_format": "jpeg",
"to_format": "png",
"quality": 90,
},
headers={"X-API-Key": "YOUR_KEY"},
timeout=60,
)
resp.raise_for_status()
with open("converted.png", "wb") as f:
f.write(resp.content)
print(f"Wrote {len(resp.content)} bytes as {resp.headers.get('content-type')}")
const url = new URL("https://image.toolkitapi.io/v1/image/convert");
url.search = new URLSearchParams({
url: "https://example.com/photo.jpg",
from_format: "jpeg",
to_format: "png",
quality: "90",
});
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const buf = Buffer.from(await resp.arrayBuffer());
require("fs").writeFileSync("converted.png", buf);
Common parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes* | Public URL to source image |
image |
string | Yes* | Base64-encoded image data (POST extract/convert only) |
from_format |
string | Yes (convert) | Source format: png, jpeg, webp, gif, bmp, tiff, avif, svg, heic, heif, apng |
to_format |
string | Yes (convert) | Target format: png, jpeg, webp, gif, bmp, tiff, avif, pdf, ico, svg, apng |
quality |
integer | No | Output quality 1–100 (JPEG/WebP/AVIF). Default: 85 |
width / height |
integer | No | Resize the output, 1–8192 px |
scale |
float | No | Scale factor (SVG conversion), 0.1–10.0. Default: 1.0 |
background |
string | No | Background colour hex for transparent-to-opaque conversions |
size |
integer | No | ICO output size, 16–256 px. Default: 32 |
count |
integer | No | Number of dominant colours to return (1–20, default 6) |
*Exactly one of url or image.
Vector-tracing options (raster → SVG)¶
| Parameter | Type | Default | Description |
|---|---|---|---|
colormode |
string | color |
color or binary |
filter_speckle |
integer | 4 |
0–128. Discard speckles smaller than this |
color_precision |
integer | 6 |
1–10. Fewer colours = smaller SVG |
corner_threshold |
integer | 60 |
0–180. Lower = smoother curves |
filename |
string | null |
Download filename for the GET variant, max 255 chars |
Error cases¶
| Status | When it happens | Fix |
|---|---|---|
400 |
Unsupported conversion pair (e.g. png → heic) |
Check validate_image_conversion's supported matrix |
400 |
Source image could not be fetched or decoded | Confirm the URL is public and returns an image |
400 |
Invalid hex in background |
Use #rgb or #rrggbb |
401 |
Missing or invalid X-API-Key |
Send the header |
404 |
No favicon found for <host> |
The domain has no discoverable icon; handle this case |
422 |
Both url and image supplied, or neither |
Provide exactly one |
422 |
quality outside 1–100, or size outside 16–256 |
Clamp to the documented range |
Tip
Use GET endpoints when you want a raw binary response (suitable for <img> tags or file downloads) — they stream the file with the correct Content-Type. Use POST endpoints when you need JSON-wrapped base64 output, such as the data_uri field for embedding directly in HTML.