Nodium Screenshot API -- Screenshot Options

The definitive reference for every parameter accepted by the Screenshot API endpoints (/take, /animate, /bulk).

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

Authentication: Include your API key via the X-Access-Key header, the access_key query parameter, or the access_key JSON body field.

Source
Output
Viewport
Full Page
Element Selection
Blocking
Emulation
Wait & Timing
Caching
Authentication & Headers
JavaScript
CSS
Clip & Crop
Overlay & Effects
Metadata
Storage
PDF Specific
Video Specific
Async & Webhooks
Security
Proxy

Source

One (and only one) source parameter is required per request. If more than one is provided, the API returns a request_not_valid error.

Parameter	Type	Default	Description
`url`	string	--	URL of the web page to capture. Must be a fully qualified HTTP or HTTPS URL. The API follows redirects automatically.
`html`	string	--	Raw HTML content to render and capture. The HTML is loaded in an isolated browser context. Maximum size is governed by the request body limit (see `html_too_large` error).
`markdown`	string	--	Markdown content to render and capture. The Markdown is converted to styled HTML before rendering. Supports CommonMark and GitHub Flavored Markdown (GFM) syntax including tables, task lists, and fenced code blocks.

Notes:

When using html or markdown, the content is rendered in a blank page context. External resources referenced in the HTML (images, stylesheets, scripts) are loaded normally.
The url parameter must include the protocol scheme (http:// or https://). URLs without a scheme are rejected with url_not_valid.

bash

# Capture a URL
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png" \
  -o page.png

# Render raw HTML
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1 style=\"color:blue\">Hello Nodium</h1>", "format": "png"}' \
  -o html.png

# Render Markdown
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello Nodium\n\nThis is **bold** text.", "format": "png"}' \
  -o md.png

Output

Controls the format and delivery of the screenshot result.

Parameter	Type	Default	Description
`format`	string	`png`	Output format. Image: `png`, `jpeg` (alias `jpg`), `webp`, `avif`, `heif`, `tiff`, `jp2`, `gif`. Document: `pdf`, `html`, `markdown`. See notes below for format-specific behavior.
`response_type`	string	`by_format`	How the response body is returned. `by_format` returns the raw binary file (image, PDF, etc.). `json` returns a JSON object containing metadata and a URL to the screenshot. `empty` returns only HTTP headers with a `204 No Content` status -- useful when using webhooks or storage.
`image_quality`	integer	`80`	Compression quality from 1 (smallest file, lowest quality) to 100 (largest file, highest quality). Applies to: `jpeg`, `webp`, `png`, `tiff`, `jp2`, `avif`, `heif`. Has no effect on `gif` or document formats.
`image_width`	integer	--	Resize the output image to this width in pixels. Aspect ratio is preserved unless both `image_width` and `image_height` are specified.
`image_height`	integer	--	Resize the output image to this height in pixels. Aspect ratio is preserved unless both `image_width` and `image_height` are specified.

Format details:

Format	MIME Type	Transparency	Notes
`png`	`image/png`	Yes	Lossless. Best for UI screenshots with sharp text.
`jpeg` / `jpg`	`image/jpeg`	No	Lossy. Smaller files, good for photographs.
`webp`	`image/webp`	Yes	Modern lossy/lossless format. Excellent compression.
`avif`	`image/avif`	Yes	Next-gen format. Best compression ratio but slower encoding.
`heif`	`image/heif`	Yes	Apple ecosystem format.
`tiff`	`image/tiff`	Yes	High-fidelity archival format. Large files.
`jp2`	`image/jp2`	Yes	JPEG 2000. Good for print workflows.
`gif`	`image/gif`	Yes	Limited to 256 colors. Use for simple graphics only.
`pdf`	`application/pdf`	--	Document output. See PDF Specific parameters.
`html`	`text/html`	--	Returns the rendered page HTML source.
`markdown`	`text/markdown`	--	Returns the page content converted to Markdown.

bash

# High-quality WebP with JSON metadata
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=webp&image_quality=95&response_type=json"

# Resized JPEG thumbnail
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=jpeg&image_quality=70&image_width=640" \
  -o thumbnail.jpg

Viewport

Controls the browser viewport dimensions and device emulation.

Parameter	Type	Default	Description
`viewport_width`	integer	`1280`	Viewport width in CSS pixels. Range: 1--7680.
`viewport_height`	integer	`1024`	Viewport height in CSS pixels. Range: 1--7680.
`device_scale_factor`	float	`1`	Device pixel ratio (DPR). Range: 1--5, supports decimals (e.g., `2.625`). Set to `2` for Retina/HiDPI displays. Higher values produce larger output images.
`viewport_device`	string	--	Preset device ID that automatically configures width, height, scale factor, mobile mode, touch emulation, and user agent. Individual parameters can override preset values. See Device Presets for the complete list.
`viewport_mobile`	boolean	`false`	Enable mobile viewport meta tag handling. Automatically set to `true` when using a mobile device preset.
`viewport_has_touch`	boolean	`false`	Enable touch event emulation. Pages may render differently when touch events are available (e.g., showing mobile navigation).
`viewport_landscape`	boolean	`false`	Rotate the viewport to landscape orientation. Swaps width and height values.

How viewport_device interacts with other parameters:

When viewport_device is set, the API loads the preset values first, then applies any explicit overrides. For example, viewport_device=iphone_16_pro&viewport_width=500 uses the iPhone 16 Pro height, scale factor, and user agent, but overrides the width to 500px.

bash

# Retina desktop screenshot
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&viewport_width=1440&viewport_height=900&device_scale_factor=2" \
  -o retina.png

# iPhone 16 Pro emulation
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&viewport_device=iphone_16_pro" \
  -o iphone.png

# Custom landscape viewport
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&viewport_width=1920&viewport_height=1080&viewport_landscape=true" \
  -o landscape.png

Full Page

Captures the entire scrollable length of a page, not just the visible viewport.

Parameter	Type	Default	Description
`full_page`	boolean	`false`	Capture the full scrollable page height. When enabled, the output image height matches the total document height (up to `full_page_max_height`).
`full_page_scroll`	boolean	`true` (when `full_page` is enabled)	Physically scroll through the page before capture. This triggers lazy-loaded images, infinite scroll content, and scroll-dependent animations. Disable if the page has no lazy content and you want faster capture.
`full_page_scroll_delay`	integer (ms)	`400`	Delay in milliseconds between each scroll step. Increase this for pages with heavy lazy-loading or animations that need time to complete after scrolling.
`full_page_scroll_by`	integer (px)	viewport height	Number of pixels to scroll per step. Defaults to the viewport height. Smaller values trigger lazy-load more frequently but increase capture time.
`full_page_max_height`	integer (px)	unlimited	Maximum capture height in pixels. Acts as a safety limit to prevent extremely tall outputs from infinite-scroll pages. When the document exceeds this height, only the top portion is captured.
`full_page_algorithm`	string	`default`	Capture algorithm. `default` uses Chrome DevTools Protocol native full-page capture. `by_sections` captures the page section by section and stitches the sections together -- useful for pages with fixed/sticky headers or complex CSS transforms.

bash

# Full page with lazy-load support
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&full_page=true&full_page_scroll=true&full_page_scroll_delay=600" \
  -o fullpage.png

# Full page with height limit
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&full_page=true&full_page_max_height=15000" \
  -o capped.png

Element Selection

Capture a specific element on the page instead of the full viewport.

Parameter	Type	Default	Description
`selector`	string (CSS)	--	CSS selector of the element to capture. Only the matched element and its contents appear in the output. Prefix with `shadow/` to traverse into Shadow DOM (e.g., `shadow/.my-component`).
`selector_all`	boolean	`false`	When `true` and the selector matches multiple elements, captures all matching elements and returns them as separate images in a zip archive or JSON array (depending on `response_type`).
`selector_algorithm`	string	`default`	Capture method. `default` uses the browser-native bounding box. `clip` uses clip-based capture, which is better for partially visible or overflow-hidden elements.
`selector_scroll_into_view`	boolean	`true`	Scroll the page to bring the target element into view before capturing. Useful for triggering lazy-load on the element.
`error_on_selector_not_found`	boolean	`false`	Return an error (`selector_not_found`) when the CSS selector does not match any element on the page. When `false`, the API falls back to capturing the full viewport.
`scroll_into_view`	string (CSS)	--	Scroll the page until this CSS selector is visible, then capture the full viewport (not the element). Useful for capturing a page section in context.
`scroll_into_view_adjust_top`	integer (px)	`0`	Vertical offset adjustment when scrolling to an element. Positive values scroll further down, negative values scroll up.
`capture_beyond_viewport`	boolean	`false`	Allow capturing content that extends beyond the visible viewport boundaries.

bash

# Capture a specific element
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&selector=%23hero-section" \
  -o element.png

# Capture an element inside Shadow DOM
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&selector=shadow/.hero-banner" \
  -o shadow.png

# Capture all matching elements
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "selector": ".product-card", "selector_all": true, "response_type": "json"}'

Blocking

Remove unwanted page elements before capture: ads, cookie banners, chat widgets, trackers, and specific network requests.

Parameter	Type	Default	Description
`block_ads`	boolean	`false`	Block advertisements using community-maintained filter lists (EasyList, uBlock Origin filters). Removes ad iframes, scripts, and placeholder elements.
`block_cookie_banners`	boolean	`false`	Block GDPR/CCPA cookie consent banners and overlays. Uses a curated list of known cookie banner selectors and scripts.
`block_banners_by_heuristics`	boolean	`false`	Alternative heuristic-based banner blocking that detects and removes overlay banners by their DOM structure and CSS properties. Use as a fallback when `block_cookie_banners` is insufficient for a particular site.
`block_chats`	boolean	`false`	Block live chat widgets including Intercom, Crisp, Drift, Tawk.to, Zoho SalesIQ, Facebook Messenger, HubSpot Chat, Zendesk, and others.
`block_trackers`	boolean	`false`	Block analytics and tracking scripts (Google Analytics, Facebook Pixel, Hotjar, Mixpanel, Segment, etc.). Can improve page load speed.
`block_requests`	string[]	--	Block network requests whose URL matches any of the provided patterns. Supports wildcard () matching. Example: `["``google-analytics", ".doubleclick.net*"]`.
`block_resources`	string[]	--	Block requests by resource type. Valid types: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `xhr`, `fetch`, `websocket`, `eventsource`, `manifest`, `other`. Example: `["font", "media"]`.
`hide_selectors`	string[]	--	Hide elements matching the given CSS selectors by applying `display: none !important`. Unlike blocking, the elements still load but are hidden from the rendered output. Example: `[".popup", "#banner"]`.

bash

# Clean screenshot without distractions
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&block_ads=true&block_cookie_banners=true&block_chats=true&block_trackers=true" \
  -o clean.png

# Block specific URL patterns and hide elements
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "block_requests": ["*analytics*", "*tracking*", "*ads*"],
    "block_resources": ["font", "media"],
    "hide_selectors": [".newsletter-popup", ".cookie-banner"]
  }' -o blocked.png

Emulation

Emulate device display preferences and browser media features.

Parameter	Type	Default	Description
`dark_mode`	boolean	--	Force the CSS color scheme preference. `true` sets `prefers-color-scheme: dark`. `false` sets `prefers-color-scheme: light`. Omit the parameter to use the site's default behavior.
`reduced_motion`	boolean	`false`	Force `prefers-reduced-motion: reduce`. Disables CSS animations and transitions, resulting in a static capture.
`media_type`	string	`screen`	CSS media type emulation. `screen` (default) renders the page as displayed on a monitor. `print` renders the print stylesheet -- useful when generating PDFs.
`geolocation_latitude`	float	--	Latitude coordinate for geolocation emulation. Must be provided together with `geolocation_longitude`. Example: `48.858184` (Eiffel Tower).
`geolocation_longitude`	float	--	Longitude coordinate for geolocation emulation. Must be provided together with `geolocation_latitude`. Example: `2.294720`.
`geolocation_accuracy`	float (meters)	--	Geolocation accuracy in meters. Optional; used alongside latitude and longitude.
`timezone`	string	--	Emulated timezone using IANA timezone identifiers. Example: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Alias: `time_zone`.
`omit_background`	boolean	`false`	Render the page with a transparent background. Supported with PNG and WebP image formats, and MOV video format.

bash

# Dark mode screenshot
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&dark_mode=true" \
  -o dark.png

# Emulate Paris geolocation
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://maps.google.com&format=png&geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=10&timezone=Europe/Paris" \
  -o paris.png

# Transparent background
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&omit_background=true" \
  -o transparent.png

Wait & Timing

Control when the screenshot is taken relative to page load events, content readiness, and explicit delays.

Parameter	Type	Default	Description
`delay`	integer (seconds)	`0`	Additional wait time in seconds after the page load completes, before the screenshot is taken. Values greater than 30 require `async=true` and `timeout` greater than 300.
`wait_until`	string or string[]	`["load"]`	Browser lifecycle event(s) to wait for before capture. `load` waits for the `load` event. `domcontentloaded` waits for DOMContentLoaded. `networkidle0` waits until there are zero network connections for 500ms. `networkidle2` waits until there are at most 2 network connections for 500ms. When multiple values are given, all conditions must be satisfied.
`wait_for_selector`	string (CSS)	--	Wait until this CSS selector appears in the DOM before capture. Supports comma-separated selectors. The wait respects the global `timeout`.
`wait_for_selector_algorithm`	string	`at_least_one`	How to evaluate comma-separated selectors. `at_least_one` succeeds when any selector matches. `at_least_by_count` requires each selector to match at least once.
`timeout`	integer (seconds)	`60`	Global request timeout. Maximum: 90 seconds for synchronous requests, 300 seconds for async requests (`async=true`).
`navigation_timeout`	integer (seconds)	`30`	Timeout for the initial page navigation. If the page does not respond within this time, the request fails with `timeout_error`. Maximum: 30 seconds.

bash

# Wait for dynamic SPA content
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://app.example.com&format=png&wait_until=networkidle0&wait_for_selector=.dashboard-loaded&delay=2" \
  -o dashboard.png

# Extended timeout for slow pages
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://slow-site.example.com&format=png&timeout=90&navigation_timeout=30&wait_until=networkidle2" \
  -o slow.png

Caching

Cache screenshot results to reduce latency and avoid consuming quota on repeated requests.

Parameter	Type	Default	Description
`cache`	boolean	`false`	Enable response caching. Cached screenshots are served from CDN, are not counted against your monthly quota, and are not logged in the Dashboard.
`cache_ttl`	integer (seconds)	--	Cache time-to-live in seconds. Minimum: 14400 (4 hours). Maximum: 2592000 (30 days). If omitted when `cache=true`, the API uses a default TTL based on your plan.
`cache_key`	string	--	Custom cache key to differentiate cached versions of the same request. Useful when you want to bust or version the cache. Example: `homepage-v2`.

Cache behavior:

The cache key is derived from all request parameters combined. Changing any parameter produces a different cache entry.
Cached results are served via CDN and are publicly accessible by URL -- no API key is required to access a cached screenshot.
The cache URL is returned in the x-nodium-cache-url response header, and in the cache_url field of JSON responses.
Caching is not compatible with webhooks (webhook_url). Using both results in an error.
First request always executes the screenshot and stores the result; subsequent requests within the TTL return the cached version.

bash

# Cache for 24 hours
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400" \
  -o cached.png

# Cache with a custom key
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&cache=true&cache_ttl=86400&cache_key=homepage-dark&dark_mode=true" \
  -o cached-dark.png

Authentication & Headers

Customize the HTTP request sent to the target page, including headers, cookies, and authorization credentials.

Parameter	Type	Default	Description
`headers`	string[]	--	Custom HTTP headers injected into every request made by the browser. Format: `Header-Name:Header-Value`. Multiple headers can be provided as an array. Example: `["X-Custom:value", "Accept-Language:fr-FR"]`.
`cookies`	string[]	--	Cookies set in the browser before navigating to the target URL. Format: `name=value; Domain=domain; Path=/; Secure; HttpOnly`. Multiple cookies can be provided as an array. The `Domain` attribute is required.
`user_agent`	string	Chrome default	Custom User-Agent string sent with every request. Overridden by the user agent from `viewport_device` if both are set.
`authorization`	string	--	Value for the `Authorization` HTTP header. Supports all standard schemes: `Basic base64credentials`, `Bearer token`, `Token apikey`, etc.
`extra_headers`	object	--	Additional headers as a key-value object (POST/JSON only). Alternative to the `headers` array format. Example: `{"X-Custom": "value", "Accept-Language": "fr-FR"}`.
`bypass_csp`	boolean	`false`	Bypass the target site's Content Security Policy. Required when injecting custom scripts (`scripts`) on pages with strict CSP rules.

bash

# Authenticated screenshot with custom cookies and headers
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "format": "png",
    "authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "cookies": [
      "session=abc123; Domain=app.example.com; Secure",
      "locale=en; Domain=app.example.com"
    ],
    "headers": ["Accept-Language:en-US,en;q=0.9"],
    "user_agent": "MyApp/2.0"
  }' -o dashboard.png

JavaScript

Inject and execute custom JavaScript on the page before the screenshot is taken.

Parameter	Type	Default	Description
`scripts`	string or string[]	--	JavaScript code to execute in the page context before capture. When provided as an array, each script is executed in order. Use this to manipulate the DOM, remove elements, click buttons, or set up the page state.
`scripts_wait_until`	string[]	--	Navigation events to wait for after script execution. Required when the injected script triggers a page redirect or navigation. Values: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. If the script causes a redirect and this parameter is omitted, the API returns a `script_triggers_redirect` error.
`click`	string (CSS)	--	CSS selector of an element to click before capture. Supports `shadow/` prefix for Shadow DOM traversal. The click occurs after page load and after any `scripts` execution.
`error_on_click_selector_not_found`	boolean	`true`	Return an error if the click target selector does not match any element. Set to `false` to silently skip the click.
`hover`	string (CSS)	--	CSS selector of an element to hover over before capture. Triggers CSS `:hover` states and JavaScript `mouseenter`/`mouseover` events. Supports `shadow/` prefix.
`error_on_hover_selector_not_found`	boolean	`true`	Return an error if the hover target selector does not match any element. Set to `false` to silently skip the hover.

bash

# Remove an element and click a button before capture
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "scripts": "document.querySelector(\".modal-overlay\").remove();",
    "click": ".show-more-button",
    "delay": 1,
    "bypass_csp": true
  }' -o modified.png

# Multiple scripts executed in sequence
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "scripts": [
      "document.body.style.zoom = \"1.5\";",
      "document.querySelectorAll(\".ad\").forEach(el => el.remove());"
    ]
  }' -o zoomed.png

# Script that triggers a redirect
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "scripts": "window.location.href = \"https://example.com/landing\";",
    "scripts_wait_until": ["networkidle0"]
  }' -o redirected.png

CSS

Inject custom CSS styles into the page before the screenshot is taken.

Parameter	Type	Default	Description
`styles`	string	--	Custom CSS injected into a `<style>` tag in the page `<head>` before capture. The CSS is applied after all page stylesheets have loaded. Use this to override fonts, colors, hide elements, adjust layout, or apply any visual customization.

bash

# Custom styling: larger fonts, hidden ads, custom background
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "styles": "body { font-size: 18px; background: #f0f0f0; } .ad, .banner, .popup { display: none !important; } img { border-radius: 8px; }"
  }' -o styled.png

Clip & Crop

Crop a rectangular region from the rendered page. All four parameters must be provided together.

Parameter	Type	Default	Description
`clip_x`	integer	--	Left edge of the crop area in CSS pixels, measured from the left edge of the page.
`clip_y`	integer	--	Top edge of the crop area in CSS pixels, measured from the top of the page.
`clip_width`	integer	--	Width of the crop area in CSS pixels.
`clip_height`	integer	--	Height of the crop area in CSS pixels.

Notes:

All four clip parameters must be provided together. Omitting any one of them results in a request_not_valid error.
Clip coordinates are in CSS pixels, not device pixels. The device_scale_factor is applied after clipping, so the output dimensions are clip_width device_scale_factor by clip_height device_scale_factor.
Clip can be combined with full_page to crop a region from the full-page render.

bash

# Crop a 800x400 region from the top-left corner
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&clip_x=0&clip_y=0&clip_width=800&clip_height=400" \
  -o cropped.png

# Crop with Retina scale (output will be 1600x800 pixels)
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&clip_x=100&clip_y=200&clip_width=800&clip_height=400&device_scale_factor=2" \
  -o cropped-retina.png

Overlay & Effects

Add watermarks, blur sensitive content, and apply visual effects to the output.

Parameter	Type	Default	Description
`watermark`	string	--	Text watermark overlaid on the output image. The text is rendered with a semi-transparent appearance.
`watermark_url`	string	--	URL of an image to use as a watermark overlay. The image is downloaded and composited onto the screenshot. Supports PNG (with transparency), JPEG, and WebP.
`watermark_position`	string	`center`	Position of the watermark on the image. Values: `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `top`, `bottom`, `left`, `right`.
`watermark_opacity`	float (0--1)	`0.5`	Opacity of the watermark. `0` is fully transparent, `1` is fully opaque.
`blur`	string[]	--	CSS selectors of elements to blur in the output. Applies a Gaussian blur to matching elements. Useful for anonymizing sensitive data (emails, phone numbers, credit cards) in screenshots. Example: `[".email", ".phone-number"]`.

bash

# Text watermark
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&watermark=DRAFT&watermark_opacity=0.3" \
  -o watermarked.png

# Image watermark in the bottom-right corner
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "watermark_url": "https://example.com/logo.png",
    "watermark_position": "bottom-right",
    "watermark_opacity": 0.7
  }' -o branded.png

# Blur sensitive information
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/profile",
    "format": "png",
    "blur": [".email-address", ".phone-number", ".credit-card"]
  }' -o redacted.png

Metadata

Extract structured data from the target page alongside the screenshot. All metadata parameters are disabled by default for optimal performance. Enable only what you need.

Parameter	Type	Default	Description
`metadata_image_size`	boolean	`false`	Include the output image dimensions in the response. JSON field: `metadata.image_size.{width, height}`. Headers: `x-nodium-image-width`, `x-nodium-image-height`.
`metadata_page_title`	boolean	`false`	Extract the page `<title>` tag content. JSON field: `metadata.page_title`. Header: `x-nodium-page-title`.
`metadata_open_graph`	boolean	`false`	Extract Open Graph meta tags (title, description, image, url, type, site_name). JSON field: `metadata.open_graph`. Header: `x-nodium-open-graph`.
`metadata_icon`	boolean	`false`	Extract the favicon URL and type. JSON field: `metadata.icon.{url, type}`. Header: `x-nodium-icon`.
`metadata_fonts`	boolean	`false`	List all fonts used on the page. JSON field: `metadata.fonts`.
`metadata_content`	boolean	`false`	Extract the page content and upload to CDN. Returns a temporary URL that expires. JSON fields: `content.{url, expires}`. Headers: `x-nodium-content-url`, `x-nodium-content-expires`.
`metadata_content_format`	string	`html`	Format for content extraction. `html` returns the rendered HTML. `markdown` returns the content converted to Markdown.
`metadata_http_response_status_code`	boolean	`false`	Include the HTTP status code returned by the target site. JSON field: `http_response.status_code`. Header: `x-nodium-http-status-code`.
`metadata_http_response_headers`	boolean	`false`	Include the HTTP response headers from the target site. JSON field: `http_response.headers`. Header: `x-nodium-http-headers`.
`extract_metadata`	boolean	`false`	Convenience flag that enables `metadata_page_title`, `metadata_open_graph`, and `metadata_icon` in a single parameter.
`extract_html`	boolean	`false`	Convenience flag equivalent to `metadata_content=true&metadata_content_format=html`.
`extract_text`	boolean	`false`	Convenience flag that extracts plain text content from the page.

bash

# Extract Open Graph and title metadata
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&response_type=json&metadata_page_title=true&metadata_open_graph=true&metadata_icon=true"

# Extract page content as Markdown
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&response_type=json&metadata_content=true&metadata_content_format=markdown"

Storage

Upload the screenshot directly to your own cloud storage instead of (or in addition to) returning it in the response.

Parameter	Type	Default	Description
`storage_path`	string	--	The object key / file path in your storage bucket. Supports template variables: `{timestamp}`, `{date}`, `{reference}`, `{format}`. Example: `screenshots/{date}/{reference}.{format}`.
`storage_bucket`	string	--	Name of the storage bucket. Must be pre-configured in the Nodium Dashboard under Settings > Storage.
`storage_region`	string	--	Cloud region of the storage bucket. Example: `us-east-1`, `eu-west-1`.
`storage_provider`	string	--	Storage provider. Supported values: `s3` (Amazon S3), `gcs` (Google Cloud Storage), `azure` (Azure Blob Storage), `r2` (Cloudflare R2), `do` (DigitalOcean Spaces).

Setup:

Storage credentials must be configured in the Nodium Dashboard before use. The API does not accept raw storage credentials in the request for security reasons.

bash

# Upload screenshot directly to S3
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "json",
    "storage_path": "screenshots/{date}/{reference}.png",
    "storage_bucket": "my-screenshots",
    "storage_region": "us-east-1",
    "storage_provider": "s3"
  }'

PDF Specific

Parameters that apply only when format=pdf. These control paper size, margins, orientation, and PDF-specific rendering behavior.

Parameter	Type	Default	Description
`pdf_format`	string	`a4`	Paper size. Values: `a0`, `a1`, `a2`, `a3`, `a4`, `a5`, `a6`, `legal`, `letter`, `tabloid`. Alias: `pdf_paper_format`.
`pdf_landscape`	boolean	`false`	Landscape page orientation. When `true`, the paper width and height are swapped.
`pdf_print_background`	boolean	`false`	Include background graphics, colors, and images in the PDF output. Without this, many pages render with a white background and missing visual elements.
`pdf_margin`	string	`0`	Uniform margin applied to all four sides. Accepts CSS units: `px`, `mm`, `cm`, `in`. Example: `20px`, `10mm`, `0.5in`.
`pdf_margin_top`	string	--	Override the top margin. Takes precedence over `pdf_margin` for the top side.
`pdf_margin_right`	string	--	Override the right margin.
`pdf_margin_bottom`	string	--	Override the bottom margin.
`pdf_margin_left`	string	--	Override the left margin.
`pdf_fit_one_page`	boolean	`false`	Scale the page content to fit on a single PDF page. Useful for dashboards, reports, or any content that should not span multiple pages.
`pdf_header_template`	string	--	HTML template for the PDF page header. Rendered on every page. Supports special CSS classes: `.title` (page title), `.url` (page URL), `.date` (current date), `.pageNumber`, `.totalPages`.
`pdf_footer_template`	string	--	HTML template for the PDF page footer. Same template variables as `pdf_header_template`.

Recommended combination for high-fidelity PDF:

format=pdf&media_type=screen&pdf_print_background=true&pdf_fit_one_page=true

bash

# Generate an A4 PDF with background and margins
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=pdf&pdf_print_background=true&pdf_format=a4&pdf_margin=20mm" \
  -o document.pdf

# Letter-size landscape PDF with header and footer
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "format": "pdf",
    "pdf_format": "letter",
    "pdf_landscape": true,
    "pdf_print_background": true,
    "pdf_margin_top": "20mm",
    "pdf_margin_bottom": "20mm",
    "pdf_margin_left": "15mm",
    "pdf_margin_right": "15mm",
    "pdf_header_template": "<div style=\"font-size:10px; width:100%; text-align:center;\">Company Report</div>",
    "pdf_footer_template": "<div style=\"font-size:10px; width:100%; text-align:center;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
  }' -o report.pdf

Video Specific

Parameters for the /animate endpoint that control video recording, scroll animations, and output format. These are used in addition to all standard /take parameters.

Parameter	Type	Default	Description
`scenario`	string	`default`	Animation scenario. `default` records the page after load without any scrolling. `scroll` records a scroll animation from top to bottom (and optionally back).
`duration`	integer (seconds)	`5`	Total recording duration. Minimum: 1. Maximum: 30.
`video_format`	string	`mp4`	Video output format. Values: `mp4`, `webm`, `gif`, `mov`, `avi`. Alias: `format` (when using the `/animate` endpoint, `format` defaults to `mp4` instead of `png`).
`width`	integer	viewport width	Video frame width in pixels. Ignored if `aspect_ratio` is set.
`height`	integer	viewport height	Video frame height in pixels. Ignored if `aspect_ratio` is set.
`aspect_ratio`	string	--	Video aspect ratio. Overrides explicit width/height. Example: `16:9`, `4:3`, `1:1`.
`scroll_duration`	integer (ms)	`1500`	Duration of a single scroll action in milliseconds. Controls the speed of each scroll step.
`scroll_delay`	integer (ms)	`500`	Delay in milliseconds between scroll steps.
`scroll_by`	integer (px)	`1000`	Pixels to scroll per step.
`scroll_easing`	string	`ease_in_out_quint`	Easing function for scroll animation. Values: `linear`, `ease_in_quad`, `ease_out_quad`, `ease_in_out_quad`, `ease_in_cubic`, `ease_out_cubic`, `ease_in_out_cubic`, `ease_in_quart`, `ease_out_quart`, `ease_in_out_quart`, `ease_in_quint`, `ease_out_quint`, `ease_in_out_quint`.
`scroll_back`	boolean	`true`	Scroll back to the top after reaching the bottom of the page.
`scroll_back_algorithm`	string	`once`	How to scroll back. `once` performs a single smooth scroll up with easing. `repeat` reverses the scroll-down algorithm step by step.
`scroll_start_immediately`	boolean	`true`	Start scrolling immediately after page load, or wait for `scroll_delay` first.
`scroll_start_delay`	integer (ms)	`0`	Wait time before the first scroll action begins.
`scroll_complete`	boolean	`true`	Stop recording when the scroll animation completes (even if `duration` has not elapsed).

bash

# Record a 10-second scroll animation as GIF
curl "https://api.nodium.io/api/v1/screenshot/animate?access_key=KEY&url=https://example.com&format=gif&scenario=scroll&duration=10&scroll_easing=ease_in_out_cubic" \
  -o scroll.gif

# MP4 video with custom scroll settings
curl -X POST "https://api.nodium.io/api/v1/screenshot/animate" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "mp4",
    "scenario": "scroll",
    "duration": 15,
    "scroll_by": 500,
    "scroll_duration": 2000,
    "scroll_back": true,
    "scroll_easing": "ease_in_out_quint"
  }' -o video.mp4

Async & Webhooks

Execute screenshots asynchronously and receive results via webhook.

Parameter	Type	Default	Description
`async`	boolean	`false`	Run the screenshot asynchronously. The API returns `202 Accepted` immediately after validating credentials. The result is delivered via `webhook_url`. Required for operations that exceed 90 seconds.
`webhook_url`	string	--	URL where the API will POST the screenshot result when processing completes. The webhook receives the screenshot binary as the request body.
`webhook_sign`	boolean	`true`	Sign the webhook payload with HMAC-SHA256 using your signing key. The signature is included in the `X-Nodium-Signature` header.
`webhook_errors`	boolean	`false`	Include error details in the webhook delivery when the screenshot fails. Error information is sent in `x-nodium-error-code` and `x-nodium-error-message` headers.
`external_identifier`	string	--	Custom identifier included in webhook headers as `x-nodium-external-identifier`. Use this to correlate webhook deliveries with your internal records.

Webhook headers delivered to your endpoint:

Header	Description
`X-Nodium-Signature`	HMAC-SHA256 signature of the body (when `webhook_sign=true`)
`x-nodium-rendering-seconds`	Rendering time in seconds
`x-nodium-size-bytes`	Screenshot file size in bytes
`x-nodium-trace-id`	Unique trace ID for debugging
`x-nodium-reference`	Screenshot reference ID
`x-nodium-external-identifier`	Your custom identifier
`x-nodium-error-code`	Error code (when `webhook_errors=true` and an error occurred)
`x-nodium-error-message`	Error message (when `webhook_errors=true` and an error occurred)

bash

# Async screenshot with webhook delivery
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://heavy-page.example.com",
    "format": "png",
    "async": true,
    "webhook_url": "https://hooks.example.com/screenshot-ready",
    "webhook_sign": true,
    "webhook_errors": true,
    "external_identifier": "order-12345"
  }'

Response (202 Accepted):

json

{
  "reference": "1234567",
  "status": "processing"
}

Security

Signed URLs allow you to safely expose screenshot URLs on the client side (e.g., in <img> tags) without revealing your API key.

Parameter	Type	Default	Description
`signature`	string	--	HMAC-SHA256 signature of all request parameters, generated using your signing key. The signing key is available in the Nodium Dashboard under Settings > Signed URLs.
`expires`	integer (UNIX timestamp)	--	Expiration timestamp for the signed URL. After this time, the URL is no longer valid. Use UNIX epoch seconds.

How to generate a signed URL:

Collect all query parameters (excluding signature) and sort them alphabetically by key.
Concatenate them into a canonical string: key1=value1&key2=value2&....
Compute the HMAC-SHA256 of the canonical string using your signing key.
Hex-encode the result and append it as the signature parameter.

Enforcement: Signature validation can be made mandatory for your organization in the Dashboard under Settings > Signed URLs. When enforced, all requests without a valid signature are rejected with signature_is_required.

bash

# Signed URL (signature computed externally)
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&expires=1709654400&signature=a1b2c3d4e5f6789012345678abcdef"

Proxy

Route the browser request through a proxy server to capture pages from specific geographic locations or bypass network restrictions.

Parameter	Type	Default	Description
`proxy_url`	string	--	Full proxy URL including protocol, host, and port. Format: `http://host:port` or `http://user:password@host:port`. Alias: `proxy`.
`proxy_username`	string	--	Proxy authentication username. Alternative to embedding credentials in the URL.
`proxy_password`	string	--	Proxy authentication password. Alternative to embedding credentials in the URL.
`ip_country_code`	string	--	Route through a Nodium-managed datacenter proxy in the specified country. Supported codes: `us`, `gb`, `de`, `fr`, `it`, `es`, `jp`, `kr`, `cn`, `in`, `au`, `br`, `mx`, `ca`, `nz`, `pe`, `is`, `ie`. This parameter is overridden by `proxy_url` if both are provided.

bash

# Capture as seen from Japan using Nodium proxy
curl "https://api.nodium.io/api/v1/screenshot/take?access_key=KEY&url=https://example.com&format=png&ip_country_code=jp" \
  -o japan.png

# Custom proxy server
curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "proxy_url": "http://proxy.example.com:8080",
    "proxy_username": "user",
    "proxy_password": "pass"
  }' -o proxied.png

Nodium Screenshot API -- Screenshot Options

Table of Contents

Source

Output

Viewport

Full Page

Element Selection

Blocking

Emulation

Wait & Timing

Caching

Authentication & Headers

JavaScript

CSS

Clip & Crop

Overlay & Effects

Metadata

Storage

PDF Specific

Video Specific

Async & Webhooks

Security

Proxy