Screenshot -- Caching

Speed up repeated requests and reduce costs with screenshot caching.

Base URL: https://api.nodium.io/api/v1/screenshot

How Caching Works
Enabling Caching
Cache TTL
Custom Cache Key
Cache Response
Cache Hit Detection
Force Refresh
Benefits
Parameters Reference
Code Examples

Best Practices

How Caching Works

When caching is enabled, the Nodium API stores the rendered screenshot on a CDN. Subsequent requests with the same parameters return the cached result instead of re-rendering the page.

The cache flow:

1. Client sends request with cache=true
         |
         v
2. API computes a cache key from URL + all rendering parameters
         |
         v
3a. Cache MISS: screenshot is rendered, stored, and returned
3b. Cache HIT:  cached screenshot is returned immediately
         |
         v
4. Cache URL is included in response headers and JSON body

Cache Key Computation

The cache key is derived from a hash of all request parameters combined. This means two requests are considered identical only when every parameter matches -- including url, format, viewport_width, dark_mode, styles, and so on.

Changing any parameter produces a different cache key and triggers a fresh render.

Enabling Caching

Add cache=true to your request:

bash

curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true" \
  -o screenshot.png

Caching is disabled by default (cache=false). You must explicitly enable it for each request.

Cache TTL

The cache_ttl parameter controls how long the cached screenshot is stored, in seconds.

Setting	Value
Minimum	`14400` (4 hours)
Default	When `cache=true` is set without `cache_ttl`, the API uses a default TTL. Specify `cache_ttl` explicitly for predictable behavior.
Maximum	`2592000` (30 days)

Common TTL values:

Duration	Seconds
4 hours	`14400`
12 hours	`43200`
24 hours (1 day)	`86400`
7 days	`604800`
30 days	`2592000`

bash

# Cache for 7 days
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=604800" \
  -o screenshot.png

Custom Cache Key

By default, the cache key is computed from all request parameters. You can override this behavior with the cache_key parameter to create your own cache key:

bash

# Use a custom cache key
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400&cache_key=homepage-v2" \
  -o screenshot.png

Custom cache keys are useful when:

You want to version cached screenshots (e.g. homepage-v1, homepage-v2)
You need to group related screenshots under a predictable key
You want to force refresh a specific cached entry by changing its key
You need to share the same cached result across requests with slightly different parameters

Note: The custom cache_key replaces the auto-computed key entirely. Two requests with different parameters but the same cache_key will return the same cached result.

Cache Response

When caching is enabled, the cache URL is returned in two ways:

1. Response Header

Every response includes the x-nodium-cache-url header:

HTTP/1.1 200 OK
x-nodium-cache-url: https://cdn.nodium.io/cache/abc123.png
x-nodium-rendering-seconds: 2.34

2. JSON Response

When response_type=json, the cache URL is included in the response body:

json

{
  "screenshot_url": "https://cdn.nodium.io/screenshots/abc123.png",
  "cache_url": "https://cdn.nodium.io/cache/abc123.png",
  "metadata": {
    "image_size": { "width": 1280, "height": 1024 },
    "page_title": "Example Domain"
  }
}

The cache_url is a public, shareable URL that does not require authentication. Anyone with the URL can access the cached screenshot.

Cache Hit Detection

You can determine whether a response was served from cache by checking the response headers:

Header	Value	Meaning
`x-nodium-cache-hit`	`true`	The response was served from cache
`x-nodium-cache-hit`	`false` or absent	The screenshot was freshly rendered

When a cache hit occurs, the response is typically returned in under 100ms, compared to several seconds for a fresh render.

Force Refresh

There are two ways to bypass the cache and force a fresh screenshot:

1. Disable Caching

Send the request with cache=false (or omit the cache parameter entirely):

bash

curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png" \
  -o fresh-screenshot.png

This renders a new screenshot but does not update the existing cache entry.

2. Change the Cache Key

If you want to refresh the cache, use a unique cache_key:

bash

# Original cached request
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400&cache_key=homepage-v1" \
  -o screenshot.png

# Force refresh by changing the cache key
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400&cache_key=homepage-v2" \
  -o screenshot.png

A common pattern is to append a timestamp or version number to the cache key:

javascript

const cacheKey = `homepage-${Date.now()}`;

Benefits

Faster Response Times

Cached screenshots are served from a CDN in under 100ms, compared to 2--10 seconds for a fresh render. This is ideal for embedding screenshots in pages where load time matters.

Reduced Costs

Cached requests cost 0 credits. Only the initial render consumes a credit from your quota. All subsequent cache hits are free for the duration of the TTL.

Shareable URLs

The cache_url is a public URL that does not require an API key. You can share it with clients, embed it in emails, or use it in documentation without exposing your credentials.

Reduced Load

Caching prevents unnecessary re-renders of the same content, reducing load on both the Nodium API and the target website.

Parameters Reference

Parameter	Type	Default	Description	Example
`cache`	boolean	`false`	Enable caching. Cached screenshots are not counted against your quota.	`true`
`cache_ttl`	integer (seconds)	--	Cache time-to-live. Min: 14400 (4 hours), Max: 2592000 (30 days).	`86400`
`cache_key`	string	--	Custom cache key to override the auto-computed key.	`homepage-v2`

Code Examples

cURL

bash

# Basic caching
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400" \
  -o screenshot.png

# Cache with JSON response to get the cache URL
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=604800&response_type=json"

# Custom cache key
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=YOUR_API_KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400&cache_key=homepage-v3" \
  -o screenshot.png

Node.js

javascript

const fs = require("fs");

async function takeScreenshotWithCache() {
  const response = await fetch(
    "https://api.nodium.io/api/v1/screenshot/take",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Key": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        url: "https://example.com",
        format: "png",
        response_type: "json",
        cache: true,
        cache_ttl: 86400,
      }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.error_code}: ${error.message}`);
  }

  const data = await response.json();
  const cacheHit = response.headers.get("x-nodium-cache-hit");

  console.log(`Cache hit: ${cacheHit}`);
  console.log(`Cache URL: ${data.cache_url}`);
  console.log(`Screenshot URL: ${data.screenshot_url}`);
}

takeScreenshotWithCache();

Python

python

import requests

response = requests.post(
    "https://api.nodium.io/api/v1/screenshot/take",
    headers={"X-Access-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "format": "png",
        "response_type": "json",
        "cache": True,
        "cache_ttl": 86400,
    },
)

if response.status_code == 200:
    data = response.json()
    cache_hit = response.headers.get("x-nodium-cache-hit")

    print(f"Cache hit: {cache_hit}")
    print(f"Cache URL: {data['cache_url']}")
    print(f"Screenshot URL: {data['screenshot_url']}")
else:
    error = response.json()
    print(f"Error: {error['error_code']} - {error['message']}")

Best Practices

Set an appropriate TTL. Use shorter TTLs (4--12 hours) for frequently changing content and longer TTLs (7--30 days) for static pages.
Use response_type=json to retrieve the cache_url for sharing or embedding.
Use custom cache keys when you need predictable, versionable cache entries.
Monitor cache hits using the x-nodium-cache-hit header to understand your cache efficiency.
Caching is not compatible with webhooks. Use synchronous requests when combining caching with other features.
Cache URLs are public. Do not cache screenshots of sensitive or authenticated content if the cache URL could be shared.
Different parameters produce different cache entries. Adding dark_mode=true to an otherwise identical request creates a separate cache entry.

Screenshot -- Caching

Table of Contents

How Caching Works

Cache Key Computation

Enabling Caching

Cache TTL

Custom Cache Key

Cache Response

1. Response Header

2. JSON Response

Cache Hit Detection

Force Refresh

1. Disable Caching

2. Change the Cache Key

Benefits

Faster Response Times

Reduced Costs

Shareable URLs

Reduced Load

Parameters Reference

Code Examples

cURL

Node.js

Python

Best Practices