Render HTML to an image with one request
To turn HTML into an image, send it to CurlShot in a POST request and get back a PNG, JPEG, WebP or PDF. The HTML is rendered by a real browser, so web fonts, flexbox, grid and images work as they do on a web page. Markdown is accepted the same way. It is the simple way to make social sharing cards, certificates, receipts and reports from a template.
curl -X POST "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"html":"<h1 style=\"font: 600 64px system-ui; padding: 80px\">Hello</h1>","viewport_width":1200,"viewport_height":630}' \
--output card.pngHow to render HTML to an image in three steps
- 1
Write the HTML and CSS of the image, as you would for a web page.
- 2
Send it in a POST request, with the width and height you want.
- 3
Save the image that comes back, or let your code do it for every item.
What works in the HTML you send
The HTML is drawn by the same browser that renders web pages, so you design an image the way you build a page. A few things differ, because your HTML arrives as text and has no address of its own.
Show the table (7 rows)
| Feature | Works? | Note |
|---|---|---|
| Flexbox, grid, gradients, shadows | Yes | Modern CSS renders as in a current browser. |
| Web fonts and images | Yes | Link them with a full https:// address. Relative paths and localhost do not load. |
| Transparent background | Yes | omit_background=true with png or webp, when your HTML sets no background. |
| Exact image size | Yes | viewport_width and viewport_height set the size of the image. |
| Sharper image | Yes | device_scale_factor=2 draws the same design with twice the pixels each way. |
| One element only | Yes | selector crops the image to one element of your HTML. |
| Input size | Up to 2 MB | Send it in a POST body, not in a query string. |
- Escape any text from users or your database before it goes into the HTML.
- Send exactly one source: html, markdown or url.
What people use it for
- Open Graph and social sharing cards, one per article or product
- Certificates, tickets and badges with a name filled in
- Receipts, invoices and reports as PDF
- Charts and tables as an image for an email
For developers: one request
The same thing from your own code. It is a plain HTTP request, so it works from any language. Create a free account to get an access key.
Questions people ask
How do I convert HTML to an image?
Send the HTML to CurlShot in the html field of a POST request. The answer is the image file. Set viewport_width and viewport_height to the size the image should have.
Can I use my own fonts and images?
Yes. The HTML is rendered like a web page, so fonts and images referenced by a public address load normally.
Can I get a PDF instead?
Yes. Add format=pdf. Paper size, margins and orientation are options.
Does it take Markdown?
Yes. Send a markdown field instead of html and it is rendered as a clean, styled page.
Guides that go deeper
- CookbookHTML to image: six templates you can copySix copyable HTML and CSS templates: social card, certificate, receipt, quote card, ticket and stat card, with sizes and the rules that make them render right.
- Cheat sheetSocial preview image sizes: the OG cheat sheetOpen Graph image sizes for Facebook, LinkedIn, WhatsApp, iMessage, Discord, Slack and Google Discover, drawn to scale, with the tags and the fixes.
- Migration notesFrom html-to-image to an API: migration notesEvery html-to-image option and what replaces it in a screenshot API, plus a test of eight pages: the library and html2canvas against a real browser.
- LetterA letter to a founder about link previewsWhat Facebook, LinkedIn, WhatsApp and Slack say they do with your og:image tags, how to check a page before launch, and one card per page made from HTML.
- One numberWeb fonts in HTML to image: the 0.5 s waitOne number from 405 renders: when a page asks for its web font late, captures before 0.5 s showed the wrong font. The fix is a marker, not a longer delay.
Related tools
- Screenshot APIA screenshot API for developers. One HTTP request turns a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Full page, devices, blocking, cache, MCP.
- URL to imageConvert any URL into an image file. Paste a web address and download a PNG, JPEG or WebP screenshot of the page. Free to try, and one request by API.
- Web page to PDFTurn a web page into a PDF document from its address. Real pages, working links and selectable text. Paste the address, nothing to install. Also an API.