
Render links: a live website screenshot from a plain img tag
Showing a screenshot of a web page usually means writing a job that captures it, a place to store the file and a way to refresh it. A render link replaces all three with one URL.
· 8 min read
The problem with screenshots in HTML
A screenshot API is easy to call from a server: send a request with your API key in a header, get an image back. An image tag cannot do that. It can only ask for an address, with no headers, and putting the key in the address would hand it to every visitor.
So the usual answer is plumbing. A scheduled job calls the API, saves each file to storage, records where it went, and runs again when the picture is too old. That is a fair amount of code to show a thumbnail, and most of it is about staleness, not screenshots.
What a render link is
A render link is a URL that is itself the screenshot. It names the page to capture and the options, and ends in a signature made with your key's render secret. Open it and you get the image.
https://api.websitescreenshotworld.com/instant-snap/v1/render/0123456789ab/webp
?thumb_width=400&ttl=86400&url=https%3A%2F%2Fexample.com&sig=3f7c…The signature is what makes it safe to publish. It is made in your own code, and it covers the page address and every option, so nobody can edit a link to capture something else on your account. The API key never appears in it.
Render links are part of the Instant Snap API on the Pro, Business and Business Plus plans, and they produce images: PNG, JPEG or WebP.
Where they fit
- Link previews. A directory, a bookmark tool or a search result that shows a thumbnail beside each address.
- Email. A report that shows how a page looked today, as an ordinary image that every mail client can display.
- Social cards. An
og:imagethat is a current picture of the page being shared. - Dashboards and wall screens. A grid of the sites a team looks after, each refreshed as often as its ttl says.
- Documentation. A picture of a live page that does not go out of date the day after it is written.
Building one
Turn it on for a key, keep the secret on your server, and let a library sign.
- In the app, open Developer Tools → API Keys → Instant Snap API and choose Render links in the key's menu.
- Turn render links on. That creates the key's render secret, which starts with
wsw_rsk_. Copy it into your server's settings, for example asWSW_RENDER_SECRET. - Build links in your own code. Signing happens on your side and sends nothing.
import { RenderLink } from "@websitescreenshotworld/sdk";
const src = RenderLink.build({
renderSecret: process.env.WSW_RENDER_SECRET ?? "",
keyPrefix: "0123456789ab",
url: "https://example.com",
format: "webp",
thumbWidth: 400,
ttl: 86_400,
});
// <img src={src} alt="example.com" width="400" />Every official client library builds render links the same way: Node.js, Python, .NET, Go, Java, PHP and Ruby. The command line does too, which is handy for a link you want to paste somewhere by hand:
wsw render-link https://example.com --format webp --thumb-width 400 --ttl 86400 --htmlOptions go in the query under their API names, and anything you leave out takes its default: a 1920 × 1080 desktop window, for instance. A name the API does not know is refused, so a typo shows up the first time you open the link, not weeks later. Request headers, cookies, delivery to your own S3 bucket, callbacks and asynchronous captures have no render-link form; those stay with the ordinary capture request. The render links reference lists every option and has a link builder with a preview.
Caching and what it costs
The number to choose carefully is ttl: how long one capture is served before a view captures again. It runs from one hour to 30 days, and defaults to a day.
- Cached views are free. Within the ttl, every view gets the stored image. The answer carries a matching cache header, so a visitor's browser keeps it too.
- A view that misses the cache makes one capture, counted like any other Instant Snap capture and listed in the same request log.
- A crowd makes one capture, not a hundred. When many views of an uncached link arrive together, one captures and the rest receive its image.
- There is a ceiling. Render links make at most 60 new captures a minute for an account. Past that, viewers see the preparing picture for a few seconds.
In practice the arithmetic is simple. A page that shows 200 thumbnails with a ttl of seven days uses about 200 captures a week, however many people look at it. Match the ttl to how fresh the picture has to be: a week for a product page that changes now and then, an hour for a dashboard.
What a viewer sees
A render link always answers with an image a page can show. When there is no capture yet, it is one of three small pictures, each cached for seconds so the next view tries again:
- Preparing this screenshot. A capture is running, or could not start yet. Reloading shows the result.
- Screenshot not available right now. The account has no captures left this period.
- This page could not be captured. The website did not load in time, or refused.
A link that is not valid is different: a wrong signature, a key without render links or an option the API refuses answers with the API's JSON error, so you can read what is wrong when you open the link yourself. The X-InstantSnap-Render response header says which case answered.
Keeping the secret safe
- Keep the render secret on your server. Anyone who has it can make links that use your captures. It cannot be used as an API key.
- Never sign in the browser. Build the link on the server and send the finished address to the page.
- If the secret leaks, make a new one on the same page. Every link signed with the old one stops working at once.
- Turning render links off, or revoking the key, stops its links the same way.
FAQ
What is a render link?
A URL that answers with a screenshot of a web page. It is signed with a secret that belongs to your API key, so it works in an img tag without sending the key, and nobody can change the page or the options in it without breaking the signature.
Does every view of the image use a capture?
No. The first view makes one capture, and that image is served to every view until the link's ttl ends, from one hour to 30 days. Cached views are free. When several people open an uncached link at the same moment, one capture is made and shared.
Which plans include render links?
Pro, Business and Business Plus. Render links capture images: PNG, JPEG or WebP.
Can someone copy my link and capture other pages with it?
No. The signature covers the page address and every option, so a changed link is refused. A copied link shows the same image it always did and nothing else.
What happens if a page cannot be captured?
The link still answers with an image, so nothing on your page breaks: a small picture saying the screenshot is being prepared, is not available right now, or could not be captured. It is cached for seconds, so the next view tries again.
TL;DR
A render link is a signed URL that answers with a screenshot. Build it on your server with a client library, put it wherever an image goes, and choose a ttl that matches how fresh the picture must be. Cached views are free, and only a view that misses the cache uses a capture.