How to Use Screenshotlayer to Generate Website Thumbnails for a Directory

To generate website thumbnails for a directory with Screenshotlayer, send each listing’s canonical website URL to its screenshot API with your access key, a consistent viewport, and an output width. Store the returned image or use an available export destination such as S3 or FTP, then render it in the directory card. Keep the key on your server, cache captures instead of requesting one on every page view, and confirm the current plan and commercial-use terms before launch.

Screenshotlayer’s example uses a 1440×900 viewport and a 300-pixel thumbnail width. These are example values, not universal design requirements. The right dimensions depend on your card layout and the responsive appearance you want to capture. Screenshotlayer’s API overview and FAQ describe its request controls; check the current documentation or request builder for the exact endpoint and parameter syntax before deploying. The landing-page sample hostname appears to contain a typo, so do not copy it blindly.

1. Plan the directory capture workflow

1. Store a canonical URL per listing. Normalize the website address when a listing is created or edited. Use an absolute URL and encode it when constructing an API request.
2. Choose a consistent capture profile. Set a viewport that presents the layout you intend directory visitors to preview. Set one output width and image format for all cards.
3. Capture outside the page-view request. Use a backend job, queue, or scheduled worker to request and save thumbnails. This avoids making directory page rendering depend on a third-party screenshot request.
4. Save a stable image location. Store the returned image URL or export the image to storage you control, where available. Keep the image reference with the directory entry.
5. Refresh deliberately. Decide how often previews should change. Screenshotlayer’s FAQ says the default cache period is 2,592,000 seconds (30 days), and describes a ttl parameter for setting a lower TTL. The product page also describes a force-refresh option. Verify the current syntax and behavior before relying on either.
6. Render a fallback. Some sites may block automated capture, load slowly, or fail to render. Show a local placeholder when the image is absent or unavailable.

This is a practical integration pattern inferred from the documented API features; it is not a tested integration recipe.

2. Pick dimensions, format, and capture controls

Choice	What it affects	Practical guidance
Target URL	The website being captured	Use the canonical listing URL, encode it safely, and decide whether redirects should be accepted by your directory workflow.
Viewport	The browser-like rendering area and responsive layout	The vendor example uses 1440x900. Test the composition with your card design; a different viewport can trigger a different site layout.
Thumbnail width	The output image width in pixels	The example uses 300. Match the output to the card’s rendered size and avoid downloading a larger image than the UI needs.
Format	Image encoding and compatibility	The FAQ lists PNG by default and JPEG and GIF alternatives. The pricing page lists WebP for paid plans. Confirm the current parameter syntax and plan inclusion for the format you select.
Delay	How long capture waits before taking the screenshot	Use only when the page needs extra time to render. A longer wait can increase job duration; no independent performance measurements are available in the researched vendor material.
Custom headers	Request context such as User-Agent or Accept-Language	Set them only when your directory needs a particular language or browser context. Do not assume headers bypass a site’s bot controls.
Cache TTL / refresh	How long a captured image can be reused and when it is regenerated	Start with the documented default behavior, then choose a shorter TTL or force-refresh policy only if image freshness warrants additional capture requests.
Export destination	Where generated images are delivered	The product page advertises AWS S3 and FTP export. The pricing page associates export options with higher tiers; check whether your selected tier includes the destination you need.

Standard dimensions make cards visually consistent, but they do not guarantee that every target site will produce a useful preview. Sites with unusual responsive layouts, overlays, or access checks need fallback handling.

3. Protect the key and budget usage

• Keep the access key server-side. Do not place it in browser JavaScript, public HTML, or a client-side request URL. Treat it as a password-like credential, restrict access to the worker that needs it, and rotate it if exposed.
• Queue and deduplicate work. Avoid submitting the same URL repeatedly when a listing is opened or a page is refreshed. Reuse saved captures and coalesce refresh jobs for the same entry.
• Set a refresh policy. Most directory listings do not need a fresh screenshot on every visit. Choose a refresh interval based on how quickly listed sites change and the freshness your directory promises.
• Check plan terms before commercial launch. The pricing page accessed on 2026-10-03 displayed a free plan of 100 snapshots per month marked non-commercial, Basic at 10,000 per month for $19.99/month and labeled commercial, Professional at 30,000 for $59.99/month, and Enterprise at 75,000 for $149.99/month. These are page-displayed figures, not durable guarantees; verify current limits, billing, overages, and usage rights directly.
• Review redistribution restrictions. Screenshotlayer’s terms put credential security and subscription-limit compliance on the account holder and describe restrictions on reselling or redistributing the API service. The terms page reports a last-modified date of 2018-02-17, so check the current agreement before making a public or commercial directory dependent on it.

The FAQ describes usage notices at 75%, 90%, and 100% of an allowance and overage fees after the limit is reached. Confirm the current notification and overage rules in your account and plan details before estimating monthly cost.

4. Add generated thumbnails to directory cards

Once your backend has captured and stored an image, render the saved image reference as the card thumbnail. Give the image explicit dimensions or an aspect ratio so the card layout does not jump while it loads. Use descriptive alternative text if the preview conveys useful information; otherwise use empty alt text when the listing title already names the site.

<article class="directory-card">
  <a href="/sites/example">
    <img
      src="/media/site-previews/example.webp"
      width="300"
      height="188"
      loading="lazy"
      alt="Preview of Example site"
    >
    <h2>Example</h2>
  </a>
</article>

The example assumes the backend stores a 300-pixel-wide image at the shown path. Use dimensions and a file extension that match the actual image your capture workflow saves.

5. Troubleshoot common problems

Symptom	Likely cause	What to do
Invalid request or authentication error	The key is missing or incorrect, a parameter is malformed, or the copied endpoint is wrong.	Check the account key and current API documentation/request builder. The landing-page sample hostname has an apparent typo, so verify the hostname before use.
Thumbnail shows the wrong layout	The viewport triggers a different responsive breakpoint than expected.	Choose a viewport matching the presentation you want, then use that same value for the directory’s other entries.
Page is captured before it is ready	The site renders content after the initial page response.	Use the documented capture delay control where needed. Keep delays bounded and avoid applying a long delay to every URL without cause.
Some sites produce no useful image	The destination may block automation, present a challenge, time out, or fail to load.	Record capture failures, retain the last good image when appropriate, and show a local placeholder if none exists. The vendor material does not promise success for every site.
Images stay stale	The default cache duration is long, or your refresh path is not forcing a new capture.	Review the FAQ’s 30-day default cache and configurable lower TTL, then confirm the current force-refresh syntax and cache behavior.
Directory cards have mixed image appearance	Different widths, formats, viewports, or crop expectations were used across jobs.	Centralize a capture profile and apply it to all new and refreshed thumbnails. Regenerate old images gradually if you change the profile.
Unexpected usage or overage	Captures run on page views, duplicates are not deduplicated, or refreshes happen too often.	Move work to a queue, reuse stored images, deduplicate jobs, and monitor usage against the current plan allowance and overage policy.
Image URL stops working or is inaccessible	The returned URL may not fit your long-term storage or delivery needs.	Consider an advertised S3 or FTP export if available on your plan, or store the image in your own media system. Verify plan availability and URL retention behavior.

6. Keep the pipeline reliable and efficient

• Separate capture from serving. A directory visitor should receive an already-saved thumbnail; do not make the listing page wait for a screenshot job.
• Use bounded retries. Retry transient failures with a limit and delay between attempts. Do not retry permanent authentication or invalid-URL errors indefinitely.
• Track state per listing. Store the last successful capture time, image reference, and a failure state so refresh jobs can distinguish missing images from temporary errors.
• Preserve a last-good image. If a refresh fails, keeping the previous image usually gives the directory a better result than replacing it with a broken image.
• Load card images lazily. Browser-side lazy loading can reduce work for images below the fold. It does not change the screenshot API’s capture usage.
• Measure your own queue and storage needs. The researched vendor pages do not provide independent benchmarks, so estimate throughput and image storage from your own directory volume and capture schedule.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call API accepts a URL and returns a PNG, JPEG, WebP, or PDF. It can remove cookie and consent banners from more than 60 known platforms, along with newsletter popups and chat widgets, before capture; each cleanup step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf. It includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 screenshots. See the ScreenshotNeo API docs.

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

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)

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

For directory use, call the API from your server or capture worker, store the returned bytes, and use the stored image in your cards. Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

FAQ

Does a 300-pixel thumbnail mean the browser viewport is 300 pixels wide?

No. The vendor example pairs a 1440×900 viewport with a 300-pixel output width. Viewport controls the rendered page context; width controls the thumbnail output width.

Can I use the free Screenshotlayer plan for a commercial directory?

The pricing page accessed for this guide labels its free plan non-commercial. Check the current terms and plan descriptions; do not assume the free tier grants commercial use.

Should I capture every directory site when a visitor opens the page?

Usually, no. Save captures in advance or refresh them in a background job so directory page delivery does not wait on screenshot generation.

Does Screenshotlayer guarantee a screenshot for every URL?

The cited official material describes capture controls but does not promise successful capture of every site. Design for failed loads and automated-access blocks with a last-good image or placeholder.

Can I use the captured image URL directly in a public page?

That depends on the response and storage behavior for your chosen setup. For durable directory delivery, confirm URL retention or export the images to storage you control.