# From html-to-image to an API: migration notes

> Every 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.

Migration notes by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 5 November 2026. Page for people: https://curlshot.com/blog/migrate-from-html-to-image

html-to-image draws a node of the live page in the visitor's browser. An API such as CurlShot draws markup you send, on a server, so the move is one change plus a list of renamed options: send the markup of the node instead of the node, keep the key on your server, and map each option (quality becomes image_quality on a scale of 1 to 100, pixelRatio becomes device_scale_factor, filter becomes hide_selectors). In a test of 8 small pages on 2 November 2026, html-to-image 1.11.13 matched Chromium on 6 and html2canvas 1.4.1 on 3. Both failed on an iframe, and neither handled an image from another host without a CORS header well.

## Key facts

- The change is not a renamed function. A library draws a live node; an API draws markup you send, so state kept in the page does not travel unless it is in the markup.
- Of 12 calls and options, 10 map to request fields or settings. SVG, canvas and raw-pixel output, and the image placeholder, have no equivalent.
- Scales differ: image quality is 0 to 1 in the library and 1 to 100 in CurlShot, and the pixel ratio defaults to the visitor's screen in the library but to 1 in the API.
- In a test of 8 pages on 2 November 2026, html-to-image 1.11.13 matched the browser on 6 and html2canvas 1.4.1 on 3. Eight pages are a probe, not a benchmark.
- Keep the library for a "download as image" button on private data. Move to an API when pictures are made without a visitor, by schedule or for many pages.

## Before and after

One call in a browser, and the same job as a request.

```javascript
import { toJpeg } from 'html-to-image'

const node = document.getElementById('receipt')
const dataUrl = await toJpeg(node, {
  quality: 0.9,        // 0 to 1
  pixelRatio: 2,
  backgroundColor: '#ffffff',
  filter: (n) => !n.classList?.contains('no-print'),
})
// dataUrl is a base64 string, in the browser
```

```javascript
// In the page: take the markup of the node, not a picture of it.
const html = '<!doctype html>'
  + '<link rel="stylesheet" href="https://your-app.example/app.css">'
  + document.getElementById('receipt').outerHTML

// On your server: one request. The key stays off the page.
const response = await fetch('https://curlshot.com/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'X-Access-Key': process.env.ACCESS_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    html,
    selector: '#receipt',          // only this node
    format: 'jpeg',
    image_quality: 90,             // 1 to 100
    device_scale_factor: 2,
    hide_selectors: ['.no-print'], // like filter
    styles: 'body{background:#fff}',
  }),
})
const jpeg = Buffer.from(await response.arrayBuffer())
```

The request shapes follow the documentation of CurlShot and were not sent in this run.

## The one change: markup instead of a node

A library such as html-to-image copies a live node in the page, turns it into an SVG that holds the HTML in a foreignObject element, and draws that SVG on a canvas. [1] An API cannot reach into the visitor's page. You send the markup, and a browser on the server draws it, so the markup must be able to stand alone: full https addresses for every stylesheet, image and font.

## The option ledger

| In html-to-image | In the API | What changes |
| --- | --- | --- |
| toPng(node) | format=png (the default) | You send the markup of the node, not the node. The answer is the file itself, or JSON with a link if you ask for response_type=json. |
| toJpeg(node, { quality }) | format=jpeg and image_quality | The library takes 0 to 1; the API takes a whole number from 1 to 100, and the default is 80. |
| toBlob(node, { type: "image/webp" }) | format=webp | png, jpeg, webp and pdf are available, and mp4, webm and gif for a scrolling video. |
| pixelRatio | device_scale_factor | The library uses the pixel ratio of the visitor’s screen unless you set it. The API default is 1, and the range is 1 to 3, so set it on purpose. |
| width, height | viewport_width, viewport_height, or selector | The library forces a size on the node. With the API you choose the window, or capture one element with selector and take its own size. |
| backgroundColor | a background in your CSS, or omit_background=true | There is no fill option. Paint the colour in your markup, or leave the page transparent with png or webp. |
| filter(node) | hide_selectors, or leave the node out of the markup | A function becomes a list of CSS selectors. Anything more complex is decided before you build the markup. |
| style | styles | An object of styles for the node becomes CSS text added to the page. |
| fontEmbedCSS, skipFonts | wait_until=networkidle or delay | The browser that draws the page loads its fonts itself. You wait for them instead of embedding them. |
| cacheBust | cache, cache_ttl, cache_key | Opposite default: caching is off, and a cache hit is not counted in your quota. Turn it on for cards that repeat, and change cache_key to force a fresh render. |
| imagePlaceholder | none | A failed image is not replaced by a placeholder. Fix the address, or check that it is a public https address. |
| toSvg, toCanvas, toPixelData | none | The API returns png, jpeg, webp, pdf or video, not an SVG, a canvas or raw pixels. |

## What a browser library can do that a request cannot

- **The thing on screen is not on any server.** A signed-in page, text typed into a field, a chart in the middle of an animation: the library draws what the visitor sees right now. An API draws the markup you send, and state kept in memory does not travel with the markup.
- **Nothing has to be sent anywhere.** For a "download this as an image" button on a page that holds private data, drawing in the browser keeps the data on the visitor’s machine. A request sends the markup to a service.
- **It costs nothing per picture.** A library has no quota. An API counts one screenshot per successful render, and the Free plan has a fixed number a month.

## A test of eight pages

On 2 November 2026 eight small pages were drawn by Chromium 153.0.8010.12 driven by Playwright, by html-to-image 1.11.13 and by html2canvas 1.4.1. Each test page was opened from a small server on 127.0.0.1, and a second server on another port served the files that must come from another origin. The library ran inside the page and drew the node to a PNG. The reference is a screenshot of the same element taken by the browser itself. The pictures were compared by eye, not by a score. The API of CurlShot was not part of this test.

| Page | html-to-image 1.11.13 | html2canvas 1.4.1 |
| --- | --- | --- |
| A plain card | Matches: Same layout and text. | Matches: Same layout and text. |
| A shadow and rounded corners | Matches: Same corners and shadow. | Differs: The corners came out square, and the shadow is darker. |
| A striped background and object-fit | Matches: Same stripes, same crop. | Differs: The stripes are missing, and the photo is squeezed into its box instead of cropped. |
| A filter, a blend mode and a frosted panel | Matches: Same blur and blending. | Differs: The blur and the blending were ignored: the circle is a flat yellow. |
| A web font from another origin, with a CORS header | Matches: The font was embedded and the text matches. | Matches: The text matches. |
| An image from another origin, without a CORS header | No picture: No picture. The promise was rejected with an event of type error. | Differs: A picture came back with an empty space where the image should be. |
| An iframe with its own page | Differs: The frame’s words came out as plain unstyled text, twice, and its yellow background is gone. | Differs: The frame is empty. |
| A canvas the page drew | Matches: Identical. | Matches: Identical. |

html-to-image 1.11.13 matched the browser on 6 of 8 pages and html2canvas 1.4.1 on 3 of 8. Eight pages say nothing about your own, which is why step 4 below uses five of yours. The list of CSS that html2canvas does not support is on its own site. [2]

## What the library does well

On six of the eight pages html-to-image 1.11.13 drew what the browser drew. Its limits are of the method: an image from another host without a CORS header cannot be read, an iframe is not drawn as a page, and its own notes say a very large DOM can fail. [1] If your pages stay inside those limits and the picture is made while the visitor looks at the page, the library is a fine choice.

## Five steps to move

1. **Make the markup stand alone.** Every stylesheet, image and font must have a full https address that is reachable from the public internet. Addresses on localhost or a private network are blocked, and relative paths have nothing to be relative to.
2. **Move the call to your server.** The access key must not be in a web page. Build the request on your server, or sign the link so that the page never holds a usable key.
3. **Translate the options.** Use the ledger above. Start with format, image_quality, device_scale_factor and selector; most calls need nothing else.
4. **Compare five of your own pages.** Draw the same five nodes with the library and with the API, and put the pictures side by side. Look at the places this test found: corners, blur, frames and images from other hosts.
5. **Turn on the cache for repeats.** A card for the same article is the same card. Set cache=true so that a repeat costs no screenshot, and change cache_key when the card really changed.

Start on the Free plan, which needs no card: see [pricing](https://curlshot.com/pricing). The page [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown) lists every rule for markup.

## Questions

### How do I replace html-to-image with an API?

Send the markup of the node to the API instead of the node itself, from your server. Make the markup stand alone with full https addresses, then map the options: format for the output, image_quality for quality, device_scale_factor for pixelRatio, selector to capture one element. CurlShot accepts the markup in the html field of a POST request.

### Why does html-to-image fail on an image from another site?

The library fetches each image and embeds it, and a browser only lets a script read an image from another origin when that server sends a CORS header. In a test on 2 November 2026 a page with such an image produced no picture from html-to-image 1.11.13, and html2canvas 1.4.1 left an empty space. A server-side browser draws the page as it would any page, so it does not need to read the image's bytes.

### Does html2canvas support box-shadow and CSS filters?

Its own list names box-shadow, filter, mix-blend-mode, object-fit and repeating-linear-gradient as unsupported. [2] In the test on 2 November 2026, html2canvas 1.4.1 drew the shadow but with square corners, ignored a blur and a blend mode, and lost a repeating gradient and the crop of object-fit.

### Is html-to-image or an API better for generating images?

For a button that downloads what the visitor sees, the library is simpler and keeps the data on their machine. For images made on a schedule, for many pages, or with no browser open, a request to an API is the way. The two are not rivals; many products use both.

### How much does it cost to generate an image with the API?

Each successful render counts as one screenshot, and a cache hit does not. The Free plan of CurlShot has 100 a month without a card (read from the pricing page on 2026-11-02). See the pricing page for the paid plans.

## Sources

1. GitHub, bubkoo/html-to-image, "html-to-image: generates an image from a DOM node using HTML5 canvas and SVG (README)": https://github.com/bubkoo/html-to-image (checked 2 November 2026)
2. html2canvas, "html2canvas: supported and unsupported CSS properties": https://html2canvas.hertzen.com/features (checked 2 November 2026)

## Go deeper

- [HTML to image](https://curlshot.com/tools/html-to-image)
- [Open Graph image generator](https://curlshot.com/tools/open-graph-image-generator)
- [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown)
- [Pricing](https://curlshot.com/pricing)

## Read next

- [HTML to image: six templates you can copy](https://curlshot.com/blog/html-to-image-templates.md): Six 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.
- [Social preview image sizes: the OG cheat sheet](https://curlshot.com/blog/social-preview-image-sizes.md): Open Graph image sizes for Facebook, LinkedIn, WhatsApp, iMessage, Discord, Slack and Google Discover, drawn to scale, with the tags and the fixes.
- [Website screenshot code examples in 8 languages](https://curlshot.com/blog/screenshot-code-examples.md): The shortest working code to save a full-page screenshot of a website in curl, Node.js, Python, PHP, Go, Ruby, Java and C#, side by side.
