Skip to content

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.

Request
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.png

How to render HTML to an image in three steps

  1. 1

    Write the HTML and CSS of the image, as you would for a web page.

  2. 2

    Send it in a POST request, with the width and height you want.

  3. 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)
FeatureWorks?Note
Flexbox, grid, gradients, shadowsYesModern CSS renders as in a current browser.
Web fonts and imagesYesLink them with a full https:// address. Relative paths and localhost do not load.
Transparent backgroundYesomit_background=true with png or webp, when your HTML sets no background.
Exact image sizeYesviewport_width and viewport_height set the size of the image.
Sharper imageYesdevice_scale_factor=2 draws the same design with twice the pixels each way.
One element onlyYesselector crops the image to one element of your HTML.
Input sizeUp to 2 MBSend 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.

Take as many screenshots as you need

A free account gives you 100 screenshots every month and keeps them in one place. No card needed.