Generation and Watermarking¶

Generate placeholder images, QR codes, barcodes, watermarks, and rendered HTML templates — all from the Image Toolkit API.

Endpoints¶

Method	Endpoint	Purpose
`POST`	`/v1/image/placeholder`	Generate placeholder images (JSON/base64)
`GET`	`/v1/image/placeholder`	Return raw placeholder image bytes
`POST`	`/v1/image/qr`	Generate QR codes (JSON/base64)
`GET`	`/v1/image/qr`	Return raw QR code bytes
`POST`	`/v1/image/barcode`	Generate barcodes (JSON/base64)
`GET`	`/v1/image/barcode`	Return raw barcode bytes
`POST`	`/v1/image/watermark/text`	Add a text watermark
`POST`	`/v1/image/watermark/image`	Add a logo or image watermark
`POST`	`/v1/image/from-template`	Render an HTML/Liquid template as an image

Examples¶

Generate a placeholder image¶

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", "format": "png"}'

import requests
import base64

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", "format": "png"},
)
data = resp.json()
with open("placeholder.png", "wb") as f:
    f.write(base64.b64decode(data["image"]))

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", bg_color: "#3B82F6", format: "png" }),
});
const data = await resp.json();
// data.image is base64-encoded PNG

Add a text watermark¶

curl -X POST "https://image.toolkitapi.io/v1/image/watermark/text" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "text": "© Toolkit API", "position": "bottom-right", "opacity": 0.5, "font_size": 32}'

import requests

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/watermark/text",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "url": "https://example.com/photo.jpg",
        "text": "© Toolkit API",
        "position": "bottom-right",
        "opacity": 0.5,
        "font_size": 32,
        "font_color": "#FFFFFF",
        "format": "jpeg",
    },
)
data = resp.json()
print("Watermark applied")

const resp = await fetch("https://image.toolkitapi.io/v1/image/watermark/text", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/photo.jpg",
    text: "© Toolkit API",
    position: "bottom-right",
    opacity: 0.5,
    font_size: 32,
    font_color: "#FFFFFF",
    format: "jpeg",
  }),
});
const data = await resp.json();

Add an image watermark (logo overlay)¶

curl -X POST "https://image.toolkitapi.io/v1/image/watermark/image" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg", "watermark_url": "https://example.com/logo.png", "position": "top-left", "opacity": 0.8, "scale": 0.15}'

import requests

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/watermark/image",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "url": "https://example.com/photo.jpg",
        "watermark_url": "https://example.com/logo.png",
        "position": "top-left",
        "opacity": 0.8,
        "scale": 0.15,  # 15% of the base image width
    },
)

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 requests
import base64

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",
    },
)
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']})")

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>{{ 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 (watermark, barcode embed)
`image`	string	Base64-encoded image data (alternative to url)
`format`	string	Output format: `png`, `jpeg`, `webp`
`width`	integer	Output width in pixels
`height`	integer	Output height in pixels

Template-specific¶

Parameter	Type	Description
`template`	string	HTML with Liquid template variables (e.g. `{{ title }}`)
`variables`	object	Key-value pairs to render in the template
`dark_mode`	boolean	Apply dark mode colour-scheme. Default: false
`wait_for`	integer	Extra wait time in ms for font/web fonts to load

Watermark-specific¶

Parameter	Type	Description
`position`	string	`top-left`, `top-right`, `bottom-left`, `bottom-right`, `center`
`opacity`	float	0.0–1.0. Default: 0.5
`scale`	float	Relative to base image width. Default: 0.15

Tip

The from-template endpoint supports Liquid template syntax ({{ variable }}, {% if %}, {% for %}). Use it to generate social cards, blog banners, email headers, or any dynamic image at scale — no Puppeteer or headless browser required on your side.

Processing & Filters

Extraction & Conversion