Instant Snap API
Render links: a screenshot URL for an img tag
A render link is a URL that is itself a screenshot. Put it wherever an image goes - an img tag, an email, a social preview - and the page appears. Only a view that is not already cached makes a capture.
What a render link is
https://api.websitescreenshotworld.com/instant-snap/v1/render/{key_prefix}/{format}?url=…&sig=…The API usually needs an X-Api-Key header, which an image tag cannot send. A render link carries a signature instead: it is made with your key's render secret, in your own code, and nobody can change the page or the options in a link without breaking it.
https://api.websitescreenshotworld.com/instant-snap/v1/render/0123456789ab/webp?thumb_width=400&ttl=86400&url=https%3A%2F%2Fexample.com&sig=3f7c…Render links are on the Pro, Business and Business Plus plans. They capture images: PNG, JPEG or WebP.
Turn it on
- 1
Open the key
In the app, go to Developer Tools, API Keys, Instant Snap API, and choose Render links in the key's menu. - 2
Turn on render links
This makes the key's render secret (wsw_rsk_…). Copy it into your server's settings, for example WSW_RENDER_SECRET. - 3
Note the key prefix
The 12 characters after wsw_api_ in the key, also shown in the key list. Links name the key by it.
The same page has a link builder with a preview, for trying options before writing any code.
Build a link
Every official client library builds render links, and so does the command line. They sign on your side and send nothing; the link is ready to use straight away.
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,
});Options
A link takes the capture options by their API names, in the query. An option you leave out takes its default, as for POST /captures.
| Field | Type | Default | Description |
|---|---|---|---|
urlRequired | string | — | The page to capture. |
ttl | integer | 86400 | Seconds a capture of the link is served before a view captures again: 3600 (an hour) to 2592000 (30 days). |
width, height, device_scale_factor | number | 1920, 1080, 1 | The browser window. |
device_category, emulated_device | string | — | desktop or mobile; a phone or tablet from the catalog. |
scroll_mode, auto_height, max_height | string, boolean, integer | — | scroll for the full page; how tall it may grow. |
zoom, block_ads, block_pop_ups, press_escape | integer, boolean | — | As for a capture: ads and pop-ups are blocked unless set to false. |
page_timeout_ms, scrolling_delay_ms, locale, time_zone | integer, string | — | As for a capture. |
hide, xpath, click, hover | string | — | The capture's selectors: hide elements, capture one element, click or hover first. |
country | string | — | Capture from another country, such as gb. |
thumb_width | integer | — | Shrink the image to this width (16 to 3840), keeping its proportions. |
sigRequired | string | — | The signature. Always last; your library writes it. |
Headers, cookies, S3 delivery, callbacks and async have no render-link form; use POST /captures for those. A name the API does not know is refused, so a typo is found the first time the link is opened.
Caching and cost
- Cached views are free. We keep each capture for the link's
ttland serve it to every view in that time without capturing again. The answer carries a matchingCache-Controlheader, so a viewer's browser keeps it too. - A view that misses the cache makes one capture, counted like any other Instant Snap capture and recorded in your Instant Snap request log like any other.
- Many visitors at once make one capture. If several views of an uncached link arrive together, one captures and the others get its image.
- At most 60 new captures a minute are made through render links for an account; past that, viewers see the preparing image for a few seconds.
Choose the ttl for how fresh the image must be
What viewers see
A render link always answers with an image a page can show. When there is no capture to show, it is one of three small pictures, cached for seconds so the next view tries again:
| Field | Type | Default | Description |
|---|---|---|---|
Preparing this screenshot | 10 s | — | A capture is running, or could not start yet. Reloading shows it. |
Screenshot not available right now | 60 s | — | Your account has no captures left this period. |
This page could not be captured | 60 s | — | The website did not load in time or refused the capture. |
A link that is not valid - a wrong signature, a key without render links, a plan without them, or an option the API refuses - answers with the API's JSON error instead, so you can read it when you open the link yourself. The X-InstantSnap-Render header says which of these answered: stored, captured, preparing, limit_reached or failed.
Signing without a library
Write every parameter except sig as name=value (booleans as true/false, numbers in their shortest form), percent-encode names and values per RFC 3986 (everything but A-Z a-z 0-9 - . _ ~, upper-case hex, so a space is %20), sort them by name and join them with &:
canonical = "/instant-snap/v1/render/{key_prefix}/{format}?" +
join("&", sorted(rfc3986(name) + "=" + rfc3986(value)
for every parameter except sig))
sig = lowercase_hex(hmac_sha256(key = render_secret, message = canonical))
link = "https://api.websitescreenshotworld.com" + canonical + "&sig=" + sigThe client libraries are tested against the same examples as the API, in render-link-vectors.json; test your own code against them too.
Keeping it 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.
- Make a new secret on the same page if it leaks: every link signed with the old one stops working at once, though a browser that already has the image may keep showing it until its
ttlends. - Turning render links off, or revoking the key, stops its links the same way.
Did this page answer your question?
Tell us what is missing