An HTML to image API renders markup in a browser engine and screenshots the result. A template API fills named layers on a design drawn in an editor. Both turn data into a picture; the difference is who can change the layout after launch, and what that costs you.
What an HTML to image API gives you
Full CSS and a real browser. Puppeteer controls Chrome or Firefox over the DevTools Protocol or WebDriver BiDi, and Playwright takes screenshots of a page or a single element. Hosted services such as HTMLCSStoImage wrap that approach: send HTML and CSS, or a URL, and receive an image. If the thing you need to capture already exists as a web page, this is the shortest path.
Where it costs you
The layout lives in code. A designer who wants a bigger headline files a ticket, an engineer edits markup, and the change ships with a deploy. You also own font loading, wait-for-network timing, and the browser itself.
The lightweight variant has its own ceiling. Next.js documents that ImageResponse supports only flexbox and a subset of CSS properties, that display: grid will not work, and that the bundle is capped at 500KB including fonts and images. Satori, the engine underneath, publishes the exact list of supported properties.
What a template API gives you
A designer draws the layout once and names the layers that change. Your code sends JSON:
{
"template": "<design-id>",
"format": "png",
"layers": { "headline": { "text": "Ship the new pricing page" } }
}Unknown layer names fail with a 422, and production pins a template version, so a layout edit never rewrites an image you already published. The cost is range: you can only produce what the editor can draw. There is no arbitrary HTML, no web components, and no capturing a live URL.
How to choose
| You need | Better fit |
|---|---|
| A screenshot of a live, public page | HTML to image API |
| Arbitrary CSS, grid, or web components | HTML to image API |
| A different layout on every request | HTML to image API |
| One layout, thousands of records | Template API |
| A designer changing the layout without a deploy | Template API |
| A strict payload that rejects typos | Template API |
If the layout stays the same and only the data changes, use a template API. If the page itself is the content, screenshot it. The longer account of why one team left Puppeteer is in Why I Built a JSON-to-Image API Instead of Puppeteer.
FAQ
What is an HTML to image API?
A service that loads HTML and CSS, or a URL, in a headless browser and returns a screenshot as PNG, JPG, or WebP. You control the markup directly, which makes it flexible and puts layout ownership with developers.
When should I use a template API instead?
Use a template API when one layout repeats with changing data, such as Open Graph cards, certificates, or product banners, and when a designer needs to edit the layout without a code deploy.
Can a template API screenshot a URL?
No. jsontoimg renders designs you build in its editor and fills their named layers. For capturing an existing web page, use a screenshot or HTML to image service.
Is Satori or Next.js ImageResponse an HTML to image API?
It converts JSX and a CSS subset to PNG inside your own app. It is lighter than a headless browser, but flexbox only, with a 500KB bundle cap, and the layout still lives in code.
Related Resources
- How JSON-to-image conversion works — the pillar guide
- Image generation API: 8 questions — the wider buyer checklist
- Build vs buy for image generation — what a self-hosted renderer costs
- Named-layer image templates — how layers work