Screenshot API
API Reference

Generate Screenshot

The core engine. Captures a full, high-fidelity PNG of any public URL with fine-grained control over viewport, theming, caching, and speed.

POST/api/screenshot

Description

Sends the target URL to a warm headless browser instance, intercepts non-essential network traffic when speed is prioritized, then returns a binary PNG. Identical recent requests are served from memory in milliseconds.

Request

Send a JSON body. Required header: Content-Type: application/json

Body parameters

  • urlRequired
    string
    —
    The target HTTP(S) URL to capture. Must be publicly reachable from our servers.
  • width
    integer
    1280
    Viewport width in pixels. Range 320–3840.
  • height
    integer
    800
    Viewport height in pixels. Range 240–4320. Full page is captured regardless.
  • dark_mode
    boolean
    false
    Emulates the OS prefers-color-scheme: dark setting before rendering.
  • is_thumbnail
    boolean
    false
    If true, the rendered image is downscaled and compressed to a 320×200 thumbnail.
  • use_cache
    boolean
    true
    When true, identical recent requests are served instantly from in-memory cache.
  • optimize_speed
    boolean
    true
    Blocks heavy media (video, large images) and custom fonts during render to dramatically reduce latency.

Example request body

{
  "url": "https://stripe.com",
  "width": 1440,
  "height": 900,
  "dark_mode": true,
  "is_thumbnail": false,
  "use_cache": true,
  "optimize_speed": true
}

Code examples

curl -X POST "https://api.example.com/api/screenshot" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "url": "https://example.com",
  "width": 1280,
  "height": 800,
  "dark_mode": false,
  "is_thumbnail": false,
  "use_cache": true,
  "optimize_speed": true
}' \
  --output screenshot.png

Response

200 OK — a raw binary PNG with Content-Type: image/png. The body is the image bytes; pipe it to a file or wrap it in a Blob in the browser.

Errors return JSON
On render failure the API responds with HTTP 500 and a JSON body of the form {"detail": "..."}. See the error handling page for common causes.

Build it visually

Prefer to click instead of type? Use the interactive Playground to assemble a request and copy a ready-to-paste snippet.