Template Rendering

2 endpoints for rendering HTML content and Liquid templates as raster images. Uses a headless Chromium browser to produce pixel-perfect output suitable for social cards, Open Graph images, certificates, or dynamic banners.

Method Endpoint Purpose
POST /v1/image/from-html Render raw HTML/CSS/JS as an image
POST /v1/image/from-template Render a Liquid template with variables as an image

1. Render HTML as an Image

Provide raw HTML content (with optional inline CSS and JavaScript) and render it as a PNG, JPEG, or WebP image.

curl -X POST "https://image.toolkitapi.io/v1/image/from-html" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body style=\"background:#1a1a2e;color:#fff;display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif\"><h1>Hello World</h1></body></html>",
    "width": 1200,
    "height": 630,
    "format": "png"
  }'
import requests

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/from-html",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "html": "<h1 style='color: blue;'>Hello World</h1>",
        "width": 1200,
        "height": 630,
        "full_page": False,
        "format": "jpeg",
        "quality": 90,
        "dark_mode": False,
    },
)
data = resp.json()
# Save the base64 image
import base64
with open("output.png", "wb") as f:
    f.write(base64.b64decode(data["image"]))
print(f"Rendered {data['width']}x{data['height']} {data['format']}")
const resp = await fetch("https://image.toolkitapi.io/v1/image/from-html", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    html: "<h1>Hello World</h1><p>Rendered server-side.</p>",
    width: 1200,
    height: 630,
    format: "png",
  }),
});
const data = await resp.json();
// data.image contains base64-encoded PNG
Response
{
  "image": "iVBORw0KGgo... (base64)",
  "upload_url": null,
  "format": "png",
  "width": 1200,
  "height": 630
}

Request Fields (from-html)

Field Required Default Description
html Yes — HTML content to render (max 1 MB)
width No 1280 Viewport width (320–3840 px)
height No 720 Viewport height (200–2160 px)
full_page No false Capture full scrollable page instead of viewport
delay No 0.0 Seconds to wait before capture (0–30)
dark_mode No false Emulate prefers-color-scheme: dark
device_scale_factor No 1.0 Pixel ratio (0.5–3.0; 2.0 = retina)
format No "png" Output format: png, jpeg, or webp
quality No null Quality 1–100 (jpeg/webp only; not for png)
clip No null Crop region {x, y, width, height}
inject_css No null Extra CSS to inject before capture (max 10k chars)
inject_js No null JavaScript to execute before capture (max 10k chars)

Validation Rules

  • quality cannot be set when format is "png".
  • clip and full_page cannot be used together.

2. Render a Liquid Template as an Image

Write a Liquid HTML template (inline or via URL), provide variables, and render the result as an image.

curl -X POST "https://image.toolkitapi.io/v1/image/from-template" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "<h1>{{ title }}</h1><p>{{ body }}</p>",
    "variables": {"title": "Hello World", "body": "Welcome to the API!"},
    "width": 1200,
    "height": 630,
    "format": "png"
  }'
import requests, base64

resp = requests.post(
    "https://image.toolkitapi.io/v1/image/from-template",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "template_url": "https://example.com/templates/card.html",
        "variables": {"name": "Alice", "score": "98%"},
        "width": 1200,
        "height": 630,
        "format": "jpeg",
        "quality": 85,
    },
)
data = resp.json()
print(f"Rendered {data['width']}x{data['height']} from {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: "<h1>{{ heading }}</h1>",
    variables: { heading: "OG Image" },
    width: 1200,
    height: 630,
    format: "webp",
    quality: 90,
  }),
});
const data = await resp.json();
console.log(data);
Response
{
  "image": "iVBORw0KGgo... (base64)",
  "upload_url": null,
  "format": "png",
  "width": 1200,
  "height": 630,
  "rendered_html_length": 42,
  "variables_used": ["title", "body"]
}

Request Fields (from-template)

All fields from from-html apply, plus:

Field Required Default Description
template Conditional* — Liquid template string (max 1 MB)
template_url Conditional* — Public HTTPS URL to a Liquid template
variables No {} Template variables/context
strict No false Raise error on undefined variables

*Provide exactly one of template or template_url.

Error Codes

Status Meaning
400 Invalid parameters — missing template source, quality on PNG, clip+full_page conflict
422 Template render error (Liquid syntax or undefined variable in strict mode)
500 Browser/screenshot error
502 Failed to fetch template from URL

Tips

  • Use format: "jpeg" with quality: 85 for smaller file sizes — ideal for social media cards.
  • Use format: "webp" for best compression (smaller than JPEG at same quality).
  • Set device_scale_factor: 2.0 for retina/high-DPI output (doubles pixel dimensions).
  • Inject custom CSS via inject_css to override template styles without modifying the source.
  • Use inject_js to run JavaScript before capture (e.g. for charts, DOM manipulation).
  • The delay parameter is essential for pages with JavaScript animations or async rendering.
  • For letterbox-style social cards, use 1200×630 (OG image standard) with full_page: false.