API Docs

Quick start

Put your page URL after ours. That's the whole API:

https://thumb.im/https://example.com

The most common use is an OpenGraph image, so every link you share gets a live screenshot card:

<meta property="og:image"
      content="https://thumb.im/https://example.com/pricing" />

Screenshots default to 1200x630 (the OpenGraph size), captured at 2x pixel density, and are cached after the first request. Query strings on your URL are preserved.

Getting started

1. 1. Create an account. Sign up — it takes a few seconds and no card.
2. 2. Add your domain. Claim it under Domains and screenshot URLs for it start working. Until a domain is claimed, its screenshot URLs return a placeholder image rather than a capture. Optionally, verify it by publishing the token we give you as a <meta> tag or at /.well-known/thumb-im-verification.txt — that makes it yours alone.
3. 3. Use the URL. Drop it into your og:image tag. That's it — captures happen on demand and refresh themselves.

Want a designed card instead of a screenshot of a page? See Render your own HTML — no domain needed.

Options in the path

Add option segments between our domain and your URL. Combine as many as you need:

https://thumb.im/small/https://example.com
https://thumb.im/1200x630/https://example.com
https://thumb.im/small/dark/zoom:2/https://example.com
https://thumb.im/opengraph/delay:500/transparent/https://example.com

Unknown segments are ignored rather than breaking your image — a typo in a template won't take down every card on your site.

Query-parameter style

Prefer explicit parameters? /shot/ takes the same options as a query string:

https://thumb.im/shot/?url=https://example.com&size=opengraph
https://thumb.im/shot/?url=https://example.com&width=1200&height=630
https://thumb.im/shot/?url=https://example.com&color_scheme=dark&full_page=true

Parameters: url (required), size, width, height, aspect_ratio, zoom, delay, wait_until, full_page, color_scheme, transparent.

Render your own HTML

If you can write the card you want as an HTML page, send us the markup and we'll return the image — no headless browser in your build, no Playwright to install. Handy for OpenGraph cards you generate per post, per product, or per release.

curl -X POST https://thumb.im/apis/render/ \
  -H "X-API-Key: ti_..." \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body style=\"margin:0;width:1200px;height:630px;display:flex;align-items:center;justify-content:center;background:#0f172a;color:#fff;font:600 72px sans-serif\">Hello</body></html>",
    "width": 1200,
    "height": 630
  }'

You get back a permanent URL, ready to paste into a meta tag:

{
  "image_url": "https://thumb.im/rendered/<hash>.png",
  "width": 1200,
  "height": 630
}

• The URL is derived from a hash of your markup, so it never changes and is cached forever. Change the HTML, get a new URL.
• Sending the same markup twice doesn't re-render — the second call returns the existing image immediately.
• Use absolute URLs or data: URIs for images and fonts; there's no page origin to resolve relative paths against.
• Markup is capped at 256KB, dimensions at 3000px. Requests to private addresses are blocked, so subresources must be publicly reachable.
• Try it without writing any code in the generator playground.

Response behavior

• Ready: the image is served directly (200, image/png) with long cache headers and ETag/Last-Modified revalidation.
• Generating: the very first request waits briefly for the capture; if it isn't done, you get a redirect to the page's own og:image or a placeholder, with Cache-Control: no-cache so the next fetch upgrades to the real screenshot. Check the X-Screenshot-Status header programmatically.
• Fresh forever: screenshots older than two weeks re-capture automatically in the background while the current image keeps serving.
• Limits: 403 when the domain isn't on an allow list; 429 with Retry-After if you create too many new screenshots per minute. Serving cached screenshots is never rate limited.

JSON API

For programmatic control, authenticate with an API key in the X-API-Key header — create one on the API Keys page:

curl -H "X-API-Key: ti_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "size": "opengraph"}' \
  https://thumb.im/apis/screenshots/

AI agents

Download a ready-to-use skill for Claude Code and other agents from the API Keys page. It bundles instructions, a single-file Python client, and a new API key already filled in — unzip it into your agent's skills folder and it works with no setup. Each download mints its own revocable key.

Agents that can fetch a URL can read the instructions directly at /skill.md (also indexed in /llms.txt). It teaches an agent to render an OpenGraph card from HTML, screenshot a page, and verify a domain — you only supply an API key.

Organizations

Domains, screenshots, and API keys belong to an organization, not to a person — invite teammates on the Organizations page and they see the same data. Inviting and removing people is dashboard-only: an API key can read who it acts as, but never grant somebody access. Each key acts as the organization you created it in. If you belong to several, name another one you're a member of with the X-Organization header:

curl -H "X-API-Key: ti_..." \
  -H "X-Organization: acme" \
  https://thumb.im/apis/screenshots/