Generation and Watermarking¶
Generate placeholder images, overlay text or logo watermarks, and render HTML/Liquid templates as images — all from the Image Toolkit API.
Every endpoint here is versioned under /v1 and authenticated with an X-API-Key header.
Endpoints¶
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/image/placeholder |
Generate a placeholder image, returned as JSON/base64 |
GET |
/v1/image/placeholder |
Return raw placeholder image bytes (for <img src>) |
GET |
/v1/image/watermark/text |
Overlay text on an image |
GET |
/v1/image/watermark/image |
Overlay a logo or image watermark |
POST |
/v1/image/from-template |
Render an HTML/Liquid template as an image |
POST |
/v1/image/from-html |
Render raw HTML/CSS as an image |
Watermarks are GET endpoints
/v1/image/watermark/text and /v1/image/watermark/image accept query parameters only — there is no JSON request body. Sending a POST with a JSON payload returns 405 Method Not Allowed.
QR codes and barcodes live in the Barcode Toolkit
There are no /v1/image/qr or /v1/image/barcode routes. Use the Barcode Toolkit (/v1/barcode/...) for QR codes and barcodes.
Examples¶
Generate a placeholder image¶
Returns JSON with a base64-encoded image — ideal when you need the bytes inline.
curl -X POST "https://image.toolkitapi.io/v1/image/placeholder" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"width": 800, "height": 600, "text": "Hero Image", "bg_color": "#3B82F6", "text_color": "#FFFFFF", "format": "png"}'
import base64
import requests
resp = requests.post(
"https://image.toolkitapi.io/v1/image/placeholder",
headers={"X-API-Key": "YOUR_KEY"},
json={
"width": 800,
"height": 600,
"text": "Hero Image",
"bg_color": "#3B82F6",
"text_color": "#FFFFFF",
"format": "png",
},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
with open("placeholder.png", "wb") as f:
f.write(base64.b64decode(data["image"]))
print(f"Generated {data['size']['width']}x{data['size']['height']} label={data['label']!r}")
const resp = await fetch("https://image.toolkitapi.io/v1/image/placeholder", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
width: 800,
height: 600,
text: "Hero Image",
bg_color: "#3B82F6",
text_color: "#FFFFFF",
format: "png",
}),
});
if (!resp.ok) throw new Error(`placeholder failed: ${resp.status}`);
const data = await resp.json();
// data.image is base64 — drop it straight into an <img> tag:
// <img src={`data:image/png;base64,${data.image}`} />
console.log(`Generated ${data.size.width}x${data.size.height} (${data.label})`);
Response
{
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
"format": "png",
"size": { "width": 800, "height": 600 },
"label": "Hero Image"
}
Stream a placeholder directly (GET)¶
The GET variant returns raw image bytes, so you can use it as an <img src> without base64 handling.
curl "https://image.toolkitapi.io/v1/image/placeholder?width=400&height=300&text=Sample&format=png" \
-H "X-API-Key: YOUR_KEY" \
--output placeholder.png
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/placeholder",
params={"width": 400, "height": 300, "text": "Sample", "format": "png"},
headers={"X-API-Key": "YOUR_KEY"},
timeout=30,
)
resp.raise_for_status()
with open("placeholder.png", "wb") as f:
f.write(resp.content)
const url = new URL("https://image.toolkitapi.io/v1/image/placeholder");
url.search = new URLSearchParams({ width: 400, height: 300, text: "Sample", format: "png" });
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const buf = Buffer.from(await resp.arrayBuffer());
require("fs").writeFileSync("placeholder.png", buf);
Add a text watermark¶
curl -G "https://image.toolkitapi.io/v1/image/watermark/text" \
-H "X-API-Key: YOUR_KEY" \
--data-urlencode "url=https://example.com/photo.jpg" \
--data-urlencode "text=© 2024 My Brand" \
--data-urlencode "position=bottom-right" \
--data-urlencode "font_size=36" \
--data-urlencode "color=#ffffff" \
--data-urlencode "opacity=0.7" \
--data-urlencode "format=png"
import base64
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/watermark/text",
params={
"url": "https://example.com/photo.jpg",
"text": "© 2024 My Brand",
"position": "bottom-right",
"font_size": 36,
"color": "#ffffff", # note: `color`, not `font_color`
"opacity": 0.7,
"format": "png",
"quality": 85,
},
headers={"X-API-Key": "YOUR_KEY"},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
with open("watermarked.png", "wb") as f:
f.write(base64.b64decode(data["image"]))
print(f"Watermarked ({data['position']})")
const url = new URL("https://image.toolkitapi.io/v1/image/watermark/text");
url.search = new URLSearchParams({
url: "https://example.com/photo.jpg",
text: "© 2024 My Brand",
position: "bottom-right",
font_size: "36",
color: "#ffffff",
opacity: "0.7",
format: "png",
});
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
if (!resp.ok) throw new Error(`watermark failed: ${resp.status}`);
const data = await resp.json();
console.log(`Watermarked at ${data.position}`);
Response
{
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
"format": "png",
"position": "bottom-right"
}
Add an image watermark (logo overlay)¶
Note the base image parameter is base_url here — not url.
curl -G "https://image.toolkitapi.io/v1/image/watermark/image" \
-H "X-API-Key: YOUR_KEY" \
--data-urlencode "base_url=https://example.com/photo.jpg" \
--data-urlencode "watermark_url=https://example.com/logo.png" \
--data-urlencode "position=top-left" \
--data-urlencode "scale=0.15" \
--data-urlencode "opacity=0.8"
import base64
import requests
resp = requests.get(
"https://image.toolkitapi.io/v1/image/watermark/image",
params={
"base_url": "https://example.com/photo.jpg",
"watermark_url": "https://example.com/logo.png",
"position": "top-left",
"scale": 0.15, # 15% of the base image width
"opacity": 0.8,
"format": "png",
},
headers={"X-API-Key": "YOUR_KEY"},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
with open("logo-watermarked.png", "wb") as f:
f.write(base64.b64decode(data["image"]))
size = data["watermark_size"]
print(f"Logo rendered at {size['width']}x{size['height']} px")
const url = new URL("https://image.toolkitapi.io/v1/image/watermark/image");
url.search = new URLSearchParams({
base_url: "https://example.com/photo.jpg",
watermark_url: "https://example.com/logo.png",
position: "top-left",
scale: "0.15",
opacity: "0.8",
});
const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const data = await resp.json();
console.log(`Watermark size: ${data.watermark_size.width}x${data.watermark_size.height}`);
Response
{
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
"format": "png",
"position": "top-left",
"watermark_size": { "width": 300, "height": 120 }
}
Render a template as an image (social cards)¶
from-template is a POST with a JSON body — unlike the watermark endpoints.
curl -X POST "https://image.toolkitapi.io/v1/image/from-template" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "<html><body style=\"background:#0f172a;color:#fff;display:flex;align-items:center;justify-content:center;height:100%\"><h1 style=\"font-size:64px\">{{ title }}</h1></body></html>",
"variables": {"title": "Toolkit API"},
"width": 1200,
"height": 630,
"format": "png"
}'
import base64
import requests
resp = requests.post(
"https://image.toolkitapi.io/v1/image/from-template",
headers={"X-API-Key": "YOUR_KEY"},
json={
"template": (
'<html><body style="background:#0f172a;color:#fff;display:flex;'
'align-items:center;justify-content:center;height:100%">'
'<h1 style="font-size:64px">{{ title }}</h1></body></html>'
),
"variables": {"title": "Toolkit API"},
"width": 1200,
"height": 630,
"dark_mode": True,
"format": "png",
},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
with open("social-card.png", "wb") as f:
f.write(base64.b64decode(data["image"]))
print(f"OG image generated ({data['width']}x{data['height']})")
print(f"Variables used: {data['variables_used']}")
const resp = await fetch("https://image.toolkitapi.io/v1/image/from-template", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
template: '<html><body style="background:#0f172a;color:#fff;display:flex;height:100%"><h1 style="font-size:64px">{{ title }}</h1></body></html>',
variables: { title: "Toolkit API" },
width: 1200,
height: 630,
dark_mode: true,
format: "png",
}),
});
const data = await resp.json();
console.log(`Generated ${data.width}x${data.height} social card`);
Common parameters¶
| Parameter | Type | Description |
|---|---|---|
url |
string | Public URL to the source image (placeholder GET, text watermark) |
base_url |
string | Base image URL for /v1/image/watermark/image |
text |
string | Placeholder label (max 100 chars) or watermark text (max 200 chars) |
bg_color |
string | Placeholder background, hex (default #cccccc) |
text_color |
string | Placeholder label colour, hex (default #555555) |
format |
string | Output format: png, jpeg, webp |
width / height |
integer | Placeholder or viewport size in pixels |
quality |
integer | 1–100 output quality. Applies to jpeg/webp output |
Placeholder-specific¶
| Parameter | Type | Default | Description |
|---|---|---|---|
width |
integer | 400 |
1–4000 px |
height |
integer | 300 |
1–4000 px |
text |
string | "{width}x{height}" |
Custom label, max 100 chars |
Text-watermark-specific¶
| Parameter | Type | Default | Description |
|---|---|---|---|
url |
string | — | Required. Source image URL |
text |
string | — | Required. Watermark text, max 200 chars |
position |
string | bottom-right |
top-left, top-right, bottom-left, bottom-right, center |
font_size |
integer | 36 |
8–300 px |
color |
string | #ffffff |
Text colour, hex. Field is color, not font_color |
opacity |
float | 0.7 |
0.0–1.0 |
Image-watermark-specific¶
| Parameter | Type | Default | Description |
|---|---|---|---|
base_url |
string | — | Required. Base image URL |
watermark_url |
string | — | Required. Watermark image URL |
position |
string | bottom-right |
Same gravity values as above |
scale |
float | 0.2 |
0.01–1.0, as a fraction of the base image width |
opacity |
float | 0.7 |
0.0–1.0 |
Template-specific¶
| Parameter | Type | Default | Description |
|---|---|---|---|
template |
string | — | HTML with Liquid variables (max 1 MB). Mutually exclusive with template_url |
template_url |
string | — | Publicly accessible HTTPS URL containing the template |
variables |
object | {} |
Key-value pairs to render into the template |
strict |
boolean | false |
Raise an error on undefined variables |
width |
integer | 1280 |
320–3840 px |
height |
integer | 720 |
200–2160 px |
full_page |
boolean | false |
Capture the full scrollable page instead of the viewport |
delay |
float | 0.0 |
0–30 s to wait after content is set, before capture |
dark_mode |
boolean | false |
Emulate prefers-color-scheme: dark |
device_scale_factor |
float | 1.0 |
0.5–3.0 device pixel ratio (2.0 = retina) |
quality |
integer | null |
1–100. Only valid for jpeg/webp |
clip |
object | null |
{x, y, width, height} region to crop before capture |
inject_css / inject_js |
string | null |
Extra CSS/JS injected before capture (max 10 KB each) |
Error cases¶
| Status | When it happens | Fix |
|---|---|---|
400 |
Invalid image data: ... — the url/base_url did not return a decodable image |
Confirm the URL is publicly reachable and returns an image content type |
400 |
Invalid colour: ... — malformed hex in bg_color, text_color, or color |
Use #rgb or #rrggbb |
401 |
Missing or wrong X-API-Key |
Send the header on every request |
405 |
You POSTed a JSON body to a watermark endpoint |
Watermarks are GET with query params |
422 |
Validation failure: font_size out of 8–300, opacity outside 0.0–1.0, scale outside 0.01–1.0, or quality sent with format=png |
Clamp values; drop quality for PNG |
422 |
from-template given both template and template_url, or neither |
Provide exactly one |
502 |
Failed to fetch template: — template_url was unreachable |
Check the URL is public and returns HTML |
422 |
Template render error: ... — Liquid syntax error, or undefined variable with strict: true |
Fix the template, or set strict: false |
500 |
Screenshot error: ... — headless browser failure |
Retry; reduce width/height/full_page for very large pages |
Tips¶
- Watermarks are
GET. Usecurl -Gwith--data-urlencode,requests.get(params=...), orURLSearchParams. A JSON body will fail with405. - The base image param differs by endpoint:
urlfor text watermarks,base_urlfor image watermarks. - There is no
image(base64) input on these routes. All watermark and placeholder-GETendpoints take a public URL, so the service can fetch it server-side. Encode-and-upload workflows belong toPOSTendpoints such asfrom-template. from-templatesupports full Liquid —{{ variable }},{% if %},{% for %}. Use it to generate social cards, blog banners, and email headers at scale without running a headless browser yourself.- Bleed-proof your watermark:
opacityabove0.8usually reads as obtrusive;0.5–0.7stays legible without ruining the image. Combine a shorttextwithfont_sizearound 3–5% of the image width. - Keep
scaleproportional. For logo watermarks,0.1–0.2of the base width is a good default; the response'swatermark_sizetells you the exact pixel dimensions used. - Prefer
webpfor web output — materially smaller thanpngat equivalentquality, and supported by every current browser.