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.