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

GEThttps://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.

A render link
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. 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. 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. 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.

FieldTypeDefaultDescription
urlRequiredstring—The page to capture.
ttlinteger86400Seconds a capture of the link is served before a view captures again: 3600 (an hour) to 2592000 (30 days).
width, height, device_scale_factornumber1920, 1080, 1The browser window.
device_category, emulated_devicestring—desktop or mobile; a phone or tablet from the catalog.
scroll_mode, auto_height, max_heightstring, boolean, integer—scroll for the full page; how tall it may grow.
zoom, block_ads, block_pop_ups, press_escapeinteger, boolean—As for a capture: ads and pop-ups are blocked unless set to false.
page_timeout_ms, scrolling_delay_ms, locale, time_zoneinteger, string—As for a capture.
hide, xpath, click, hoverstring—The capture's selectors: hide elements, capture one element, click or hover first.
countrystring—Capture from another country, such as gb.
thumb_widthinteger—Shrink the image to this width (16 to 3840), keeping its proportions.
sigRequiredstring—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 ttl and serve it to every view in that time without capturing again. The answer carries a matching Cache-Control header, 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

A product page that changes weekly can use 7 days; a dashboard that changes hourly, an hour. The longer the ttl, the fewer captures.

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:

FieldTypeDefaultDescription
Preparing this screenshot10 s—A capture is running, or could not start yet. Reloading shows it.
Screenshot not available right now60 s—Your account has no captures left this period.
This page could not be captured60 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 &:

The signature
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=" + sig

The 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 ttl ends.
  • 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