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. Use curl -G with --data-urlencode, requests.get(params=...), or URLSearchParams. A JSON body will fail with 405.
  • The base image param differs by endpoint: url for text watermarks, base_url for image watermarks.
  • There is no image (base64) input on these routes. All watermark and placeholder-GET endpoints take a public URL, so the service can fetch it server-side. Encode-and-upload workflows belong to POST endpoints such as from-template.
  • from-template supports 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: opacity above 0.8 usually reads as obtrusive; 0.5–0.7 stays legible without ruining the image. Combine a short text with font_size around 3–5% of the image width.
  • Keep scale proportional. For logo watermarks, 0.1–0.2 of the base width is a good default; the response's watermark_size tells you the exact pixel dimensions used.
  • Prefer webp for web output — materially smaller than png at equivalent quality, and supported by every current browser.