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¶
qualitycannot be set whenformatis"png".clipandfull_pagecannot 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"withquality: 85for 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.0for retina/high-DPI output (doubles pixel dimensions). - Inject custom CSS via
inject_cssto override template styles without modifying the source. - Use
inject_jsto run JavaScript before capture (e.g. for charts, DOM manipulation). - The
delayparameter is essential for pages with JavaScript animations or async rendering. - For letterbox-style social cards, use
1200×630(OG image standard) withfull_page: false.