Website thumbnail API.

Generate website thumbnails from any URL.

1. Your codeA URLSubmitted by a user, or read from your database
2. urlshot.ioAPI requestGET or POST /v1/screenshot
3. urlshot.ioChromium rendersScripts, web fonts, lazy images
4. urlshot.ioImage returnedPNG, JPEG or WebP bytes
5. Your codeYour storageS3, R2, a CDN or a database
6. Your codeYour appAn image on the listing

• The response is the image

  No JSON wrapper and no base64: write the body to a file or stream it to storage.

• Fresh unless you ask

  Every request renders the page as it is now. Set cache_ttl to reuse a recent capture instead.

• Capture once, show often

  Store the thumbnail when a URL is added, serve it from your CDN, and refresh it on your own schedule.

Generate a thumbnail with one request.

import { writeFile } from 'node:fs/promises';

// A 1280 × 800 desktop layout, returned at half scale: a 640 × 400 WebP.
const params = new URLSearchParams({
  url: 'https://www.blender.org',
  viewport_width: '1280',
  viewport_height: '800',
  device_scale_factor: '0.5',
  format: 'webp',
  quality: '80',
  block_cookie_banners: 'true',
});

const response = await fetch(`https://api.urlshot.io/v1/screenshot?${params}`, {
  headers: { Authorization: `Bearer ${process.env.URLSHOT_API_KEY}` },
});

if (!response.ok) {
  // Anything that is not an image is the JSON error envelope.
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message} (request ${error.requestId})`);
}

await writeFile('blender-org.webp', Buffer.from(await response.arrayBuffer()));

curl -G "https://api.urlshot.io/v1/screenshot" \
  -H "Authorization: Bearer $URLSHOT_API_KEY" \
  --data-urlencode "url=https://www.blender.org" \
  --data-urlencode "viewport_width=1280" \
  --data-urlencode "viewport_height=800" \
  --data-urlencode "device_scale_factor=0.5" \
  --data-urlencode "format=webp" \
  --data-urlencode "quality=80" \
  --data-urlencode "block_cookie_banners=true" \
  --output blender-org.webp

import os, requests

response = requests.get(
    "https://api.urlshot.io/v1/screenshot",
    headers={"Authorization": f"Bearer {os.environ['URLSHOT_API_KEY']}"},
    params={
        "url": "https://www.blender.org",
        "viewport_width": "1280",
        "viewport_height": "800",
        "device_scale_factor": "0.5",
        "format": "webp",
        "quality": "80",
        "block_cookie_banners": "true",
    },
    timeout=60,
)

if response.status_code != 200:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']} ({error['requestId']})")

with open("blender-org.webp", "wb") as image:
    image.write(response.content)

On success the body is the image. Anything else, such as a bad key or a page that would not load, is a JSON error with a stable code and a request id: see errors. Every option used here is described in the parameter reference.

Or embed it without storing it

// signedUrl() is the function from the signed URL guide,
// https://urlshot.io/docs/#signed-urls
const src = signedUrl({
  url: 'https://www.blender.org',
  viewport_width: '1280',
  viewport_height: '800',
  device_scale_factor: '0.5',
  format: 'webp',
  cache_ttl: '86400',
});

// In your template, at the size the thumbnail is shown:
// <img src="${src}" width="640" height="400"
//      loading="lazy" alt="blender.org home page">

Why generate thumbnails through an API?

You can generate thumbnails with Puppeteer or Playwright on your own servers. It works, and what it takes is mostly not the capture itself:

Browser management

Chromium has to match your Puppeteer version, be patched when it has security fixes, and ship with fonts. Without them, text renders in a fallback face or as empty boxes.

With the API:The browser and its fonts are part of the service, not something you install.

Infrastructure

A browser uses far more memory and CPU than the web request that asked for it, so captures usually end up in a separate service or queue worker.

With the API:One HTTPS request from wherever your code already runs.

Concurrency

Each capture holds a page open for seconds. Twenty users adding sites at once is twenty browser pages at once, or a queue you build and operate.

With the API:Your plan’s render slots, and a concurrency_limit_exceeded error with Retry-After when they are all busy.

Timeouts

Some pages never go quiet on the network; some hang on a third-party script. Every capture needs a hard limit and a decision about what happens when it fires.

With the API:wait_until, delay_ms and timeout_ms, and a render_timeout error you can handle.

Rendering consistency

Consent dialogs, lazy-loaded images and late web fonts all change what a capture shows, and differently from one site to the next.

With the API:block_cookie_banners hides the dialogs of the major consent platforms.

Security

A directory captures URLs its users submit. A browser on your network will load an internal admin page or a cloud metadata address if someone submits one, or a public URL that redirects there.

With the API:Private and metadata addresses are refused, every redirect is checked, and each render starts in a fresh browser.

Running your own browser is the better choice when you need pages behind a login or on a private network. urlshot.io captures public pages only, without your cookies or headers. The same goes for volume large enough that a browser fleet of your own costs less than paying per screenshot.