How to Capture a Page with Lazy-Loaded Images Using HTMLCSStoImage

To capture a page with lazy-loaded images using HTMLCSStoImage, pass its fully qualified address in url and set full_screen: true. Full-screen capture scrolls through the page and stitches the result, which is intended to trigger lazy-loaded content. If images still appear blank or as placeholders, add a measured ms_delay; if you control the page JavaScript, use render_when_ready and call ScreenshotReady() once the content needed for the screenshot is ready.

1. Capture the full page

Use a public, fully qualified URL and enable full-screen capture. For example, with cURL:

curl -X POST https://hcti.io/v1/image \
  -u YOUR_USER_ID:YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article","full_screen":true}'

Use your HTMLCSStoImage credentials. The service response provides the generated image result. See the official URL-to-image guide and full_screen parameter documentation for the current request and response format.

The important setting is full_screen: it controls page coverage and causes the service to scroll through the document. A normal viewport screenshot may never bring below-the-fold images into view, so a wait alone cannot solve that coverage problem.

2. Add a wait only if images are still missing

Inspect the output for blank areas, placeholders, or images that loaded only near the top. If needed, add ms_delay, a fixed pause before image generation. The vendor FAQ suggests starting at 500 ms and adjusting to suit the page.

curl -X POST https://hcti.io/v1/image \
  -u YOUR_USER_ID:YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article","full_screen":true,"ms_delay":500}'

A delay gives asynchronous image requests extra time, but it does not check whether a specific image has loaded. Increase it only after inspecting results; longer waits increase render time. HTMLCSStoImage documents max_wait_ms as a separate maximum-wait control with a range of 500–10,000 milliseconds. It is a cap on waiting, not a promise that every remote asset will finish loading. Consult the parameter reference for the supported settings.

3. Signal readiness when you control the page

For a page whose JavaScript you can change, render_when_ready: true lets page code decide when the renderer should proceed. Call ScreenshotReady() after the images and other content needed for the capture are ready:

<script>
  async function prepareScreenshot() {
    // Perform the page-specific work that makes required content ready.
    await loadRequiredImages();
    ScreenshotReady();
  }

  prepareScreenshot();
</script>

Then request the image with both full-page capture and the readiness option enabled:

curl -X POST https://hcti.io/v1/image \
  -u YOUR_USER_ID:YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article","full_screen":true,"render_when_ready":true}'

loadRequiredImages() is an example placeholder for your own page logic; define it to resolve only when the content you need is ready. The callback gives you a page-controlled readiness signal, unlike a fixed delay. It does not replace full_screen, which is still needed to capture content below the viewport. See the FAQ for the documented readiness approach.

4. Choose the right loading strategy

Setting or approach	What it controls	Use it when	Limit
full_screen: true	Capture height and scroll-through	You need below-the-fold content and want scrolling to prompt lazy loading	Does not guarantee every site’s scripts or assets finish in time
ms_delay	Fixed pause before generating the image	A small timing buffer is enough and you cannot change the page	Time-based; it does not verify a particular image loaded
render_when_ready: true	Waits for the page’s readiness signal	You control the page JavaScript and can identify the required content	Page code must call ScreenshotReady(); a missed signal can prevent timely completion
max_wait_ms	Maximum wait window	You need to bound the renderer’s wait	Documented range is 500–10,000 ms; it is not a resource-load guarantee

5. Troubleshoot missing lazy images

Symptom	Likely cause	What to try
Images below the fold are absent	The request captured only the initial viewport	Set full_screen: true so the page is scrolled and the full height is captured.
Some images are still placeholders	The site needs more time after scrolling, or its lazy-loading script behaves differently in a renderer	Try a 500 ms ms_delay, inspect the result, then adjust in measured increments.
A longer delay does not fix one image	The image may depend on a specific event or application state; fixed waiting does not confirm that image loaded	If you control the page, wait for that content in your own readiness logic and then call ScreenshotReady().
Capture waits too long or does not complete as expected	render_when_ready is enabled but page code never signals readiness, or the wait cap is misconfigured	Ensure the callback runs on every relevant code path and review the documented max_wait_ms range.
Top content appears but the lower page is cut off	Full-height capture is not enabled	Use full_screen: true; increasing a delay does not expand the capture height.

6. Performance, reliability, and cost considerations

Full-page capture takes more work than a viewport image because the service scrolls through the document and stitches the result. A fixed delay adds time to each render, so start with the documented 500 ms suggestion and increase only when the output shows it is needed. A readiness callback can avoid guessing when you control the page, but depends on correct page code and a signal on all completion paths.

Remote images can still fail or remain unavailable because the capture process cannot make an origin serve an asset that the page itself cannot load. Check the page in a browser, use a fully qualified public URL, and verify the relevant content is reachable. The cited documentation does not provide a general cost or performance benchmark for this specific workflow; check your account and current vendor terms for pricing and limits.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. A single GET request captures a URL; full-page capture loads lazy images. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000.

For example, this cURL request saves a WebP screenshot:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Sign up free for 1,000 screenshots a month, with no card required.

Frequently asked questions

Does full-screen capture guarantee every lazy image appears?

No. Scrolling is intended to trigger lazy loading, but site scripts and asset timing vary. Inspect the output and use a delay or page-controlled readiness signal when needed.

Should I use both a fixed delay and the readiness callback?

Start with the simplest strategy that fits your control of the page. A fixed delay is useful when you cannot change page code; the callback is more explicit when you can. Follow the current parameter documentation if combining wait settings.

Is max_wait_ms the same as ms_delay?

No. ms_delay is a fixed pause. max_wait_ms sets a maximum wait window.

Can I fix missing images by increasing the wait alone?

Not if the capture never scrolls to the image. First enable full-screen capture; then tune waiting if the image still has not loaded.