Screenshot -- Screenshot URLs

Create permanent, shareable URLs that always return a fresh screenshot.

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

What Is a Screenshot URL?
Creating a Screenshot URL
Embedding in HTML
Auto-Refresh Behavior
Custom Storage

- Amazon S3 - Google Cloud Storage - Azure Blob Storage

CDN Integration
Code Examples

Best Practices

What Is a Screenshot URL?

A screenshot URL is a permanent, publicly accessible link that serves a screenshot of a web page. Unlike a raw API call that returns binary image data, a screenshot URL is a stable endpoint you can use in <img> tags, share with clients, or embed in documents.

There are two types of screenshot URLs:

Type	Description	Updates
Screenshot URL	A permanent link to the captured screenshot. Returned in the `screenshot_url` field.	Points to the screenshot as captured at request time.
Cache URL	A CDN-hosted link that serves the cached version. Returned in the `cache_url` field when `cache=true`.	Refreshes when the cache expires or is invalidated.

Screenshot URLs are ideal for:

Embedding live previews of websites in dashboards or admin panels
Sharing screenshots with clients or stakeholders via a link
Automating thumbnail generation for link previews
Integrating with CMS platforms, email templates, or documentation

Creating a Screenshot URL

To get a screenshot URL, set response_type=json on your request. The API returns a JSON response containing the screenshot_url field instead of raw binary data.

bash

curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "json"
  }'

Response:

json

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

The screenshot_url is a direct link to the rendered image. It does not require authentication to access.

Embedding in HTML

Use the screenshot_url directly in HTML <img> tags:

html

<img
  src="https://cdn.nodium.io/screenshots/abc123.png"
  alt="Screenshot of example.com"
  width="640"
  height="480"
/>

For responsive images:

html

<picture>
  <source
    media="(min-width: 768px)"
    srcset="https://cdn.nodium.io/screenshots/abc123.png"
  />
  <img
    src="https://cdn.nodium.io/screenshots/abc123-mobile.png"
    alt="Screenshot of example.com"
    style="width: 100%; height: auto;"
  />
</picture>

You can also use screenshot URLs in CSS:

css

.hero-preview {
  background-image: url("https://cdn.nodium.io/screenshots/abc123.png");
  background-size: cover;
  background-position: center;
}

Auto-Refresh Behavior

Screenshot URLs are generated at the time of the API request. To keep screenshots up to date, you have several options:

1. Periodic Re-capture

Schedule a cron job or background task to re-capture the screenshot at regular intervals:

javascript

// Run every hour to update the screenshot
async function refreshScreenshot() {
  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: 3600,
      }),
    }
  );

  const data = await response.json();
  // Store data.screenshot_url in your database
}

2. Cache-Based Refresh

Use caching with a TTL. When the cache expires, the next request to the cache URL triggers a fresh render:

bash

curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "json",
    "cache": true,
    "cache_ttl": 3600
  }'

3. On-Demand Refresh

Trigger a new screenshot whenever the source content changes (e.g. via a CMS webhook):

javascript

// Called when your CMS publishes new content
async function onContentPublished(pageUrl) {
  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: pageUrl,
        format: "png",
        response_type: "json",
      }),
    }
  );

  const data = await response.json();
  await updateScreenshotUrl(pageUrl, data.screenshot_url);
}

Custom Storage

By default, screenshots are stored on Nodium's CDN. You can configure custom storage to upload screenshots directly to your own cloud storage provider.

Note: Custom storage credentials are configured in the Nodium Dashboard under Settings > Storage. The API parameters below control the destination path and bucket for each request.

Amazon S3

json

{
  "url": "https://example.com",
  "format": "png",
  "response_type": "json",
  "storage_bucket": "my-screenshots-bucket",
  "storage_path": "screenshots/example-com.png",
  "storage_region": "us-east-1"
}

Google Cloud Storage

json

{
  "url": "https://example.com",
  "format": "png",
  "response_type": "json",
  "storage_bucket": "my-screenshots-bucket",
  "storage_path": "screenshots/example-com.png"
}

Azure Blob Storage

json

{
  "url": "https://example.com",
  "format": "png",
  "response_type": "json",
  "storage_bucket": "my-screenshots-container",
  "storage_path": "screenshots/example-com.png"
}

Storage Parameters

Parameter	Type	Description	Example
`storage_bucket`	string	Bucket or container name in your cloud storage provider.	`my-screenshots`
`storage_path`	string	File path within the bucket. Supports subdirectories.	`screenshots/2026/03/example.png`
`storage_region`	string	Storage region (required for S3).	`us-east-1`

CDN Integration

Screenshot URLs hosted on Nodium's CDN are served with appropriate caching headers and are optimized for fast delivery worldwide. When using custom storage, you can place your own CDN in front of the storage bucket.

Example: CloudFront + S3

Configure your S3 bucket as the origin in CloudFront
Set the storage_path to match your CloudFront path pattern
Use the CloudFront distribution URL to serve screenshots

json

{
  "url": "https://example.com",
  "format": "png",
  "response_type": "json",
  "storage_bucket": "my-screenshots",
  "storage_path": "captures/example-com.png"
}

The screenshot is uploaded to s3://my-screenshots/captures/example-com.png and served via https://d1234.cloudfront.net/captures/example-com.png.

Example: Cloudflare R2

Cloudflare R2 is S3-compatible. Configure your R2 credentials in the Dashboard and use the same storage_* parameters:

json

{
  "url": "https://example.com",
  "format": "png",
  "response_type": "json",
  "storage_bucket": "screenshots",
  "storage_path": "example-com.png"
}

Code Examples

cURL

bash

# Get a screenshot URL
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "json"
  }'

# Screenshot URL with custom storage
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "json",
    "storage_bucket": "my-screenshots",
    "storage_path": "captures/example-com.png",
    "storage_region": "us-east-1"
  }'

# Screenshot URL with caching
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "json",
    "cache": true,
    "cache_ttl": 86400
  }'

Node.js

javascript

async function getScreenshotUrl(targetUrl) {
  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: targetUrl,
        format: "png",
        response_type: "json",
        viewport_width: 1280,
        viewport_height: 720,
      }),
    }
  );

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

  const data = await response.json();
  return data.screenshot_url;
}

// Usage
async function main() {
  const url = await getScreenshotUrl("https://example.com");
  console.log(`Screenshot URL: ${url}`);

  // Use in HTML: <img src="${url}" />
}

main();

Python

python

import requests


def get_screenshot_url(target_url):
    response = requests.post(
        "https://api.nodium.io/api/v1/screenshot/take",
        headers={"X-Access-Key": "YOUR_API_KEY"},
        json={
            "url": target_url,
            "format": "png",
            "response_type": "json",
            "viewport_width": 1280,
            "viewport_height": 720,
        },
    )

    if response.status_code == 200:
        data = response.json()
        return data["screenshot_url"]
    else:
        error = response.json()
        raise Exception(f"{error['error_code']}: {error['message']}")


# Usage
url = get_screenshot_url("https://example.com")
print(f"Screenshot URL: {url}")

# Use in HTML: <img src="{url}" />

Best Practices

Use response_type=json to retrieve screenshot URLs. The default by_format response type returns raw binary data without a URL.
Combine with caching for cost-effective, fast-loading screenshot URLs. Cached requests cost 0 credits.
Use custom storage when you need full control over the hosting, CDN, or access policies for your screenshots.
Set storage_path with unique names to avoid overwriting previous screenshots. Include a timestamp or version in the path.
Configure storage credentials once in the Dashboard. The API parameters only control the destination path and bucket per request.
Screenshot URLs are public. Do not generate screenshot URLs for pages containing sensitive or confidential information unless you control access to the URL.
Use image_width and image_height to generate appropriately sized thumbnails for embedding, reducing bandwidth and load time.

Screenshot -- Screenshot URLs

Table of Contents

What Is a Screenshot URL?

Creating a Screenshot URL

Embedding in HTML

Auto-Refresh Behavior

1. Periodic Re-capture

2. Cache-Based Refresh

3. On-Demand Refresh

Custom Storage

Amazon S3

Google Cloud Storage

Azure Blob Storage

Storage Parameters

CDN Integration

Example: CloudFront + S3

Example: Cloudflare R2

Code Examples

cURL

Node.js

Python

Best Practices