Screenshot -- Animated Screenshots & Videos

Record scroll-through videos and animated captures of any web page.

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

What Are Animated Screenshots?
Endpoint
Video Formats
Parameters

- Core Animation - Scroll Animation - Easing Functions

Code Examples

Tips for Optimal Quality
Combining with Other Options

What Are Animated Screenshots?

Animated screenshots are short videos that capture a web page in motion. The most common use case is a scroll-through video -- a recording that automatically scrolls from the top to the bottom of a page, producing a smooth preview of the entire content.

Use cases include:

Product demos -- showcase a landing page or feature set in a single video
Social media content -- generate scroll-through GIFs for Twitter/X, LinkedIn, or Instagram
QA and review -- visually verify that lazy-loaded content renders correctly as the page scrolls
Documentation -- embed animated previews of dashboards, reports, or design systems
Marketing -- create website previews for portfolio sites or case studies

Animated screenshots support all the same rendering options as static screenshots (viewport size, device emulation, dark mode, cookie injection, and more) with additional parameters to control the animation behavior.

Endpoint

`GET/POST /animate` -- Animated Screenshot / Video

GET  https://api.nodium.io/api/v1/screenshot/animate?access_key=KEY&url=https://example.com&format=mp4
POST https://api.nodium.io/api/v1/screenshot/animate

GET: Parameters passed as query string
POST: Parameters passed as JSON body (Content-Type: application/json), or as query string, or mixed

The /animate endpoint accepts all parameters from the /take endpoint plus animation-specific parameters documented below.

Video Formats

Format	`format=`	Best For	Transparency
MP4	`mp4`	Universal video playback, web embedding	No
WebM	`webm`	Web-optimized video, smaller file size	No
GIF	`gif`	Social media, email embeds, inline previews	Yes
MOV	`mov`	Apple ecosystem, transparent background support	Yes
AVI	`avi`	Legacy systems, maximum compatibility	No

Recommendation: Use mp4 for general-purpose video. Use gif when you need inline playback without a video player (e.g. in emails or chat). Use mov when you need a transparent background (omit_background=true).

Parameters

Core Animation

Parameter	Type	Default	Description	Example
`scenario`	string	`default`	Animation scenario. `default` = records the page after load without scrolling. `scroll` = records a scroll animation.	`scroll`
`format`	string	`mp4`	Video format: `mp4`, `webm`, `gif`, `mov`, `avi`.	`gif`
`duration`	integer (seconds)	`5`	Total recording duration. Min: 1, Max: 30.	`10`
`width`	integer	viewport width	Video width in pixels. Ignored if `aspect_ratio` is set.	`1280`
`height`	integer	viewport height	Video height in pixels. Ignored if `aspect_ratio` is set.	`720`
`aspect_ratio`	string	--	Aspect ratio (overrides width/height).	`16:9`

Scroll Animation

These parameters apply when scenario=scroll.

Parameter	Type	Default	Description
`scroll_duration`	integer (ms)	`1500`	Duration of a single scroll action. Higher values produce smoother, slower scrolling.
`scroll_delay`	integer (ms)	`500`	Delay between each scroll step. Useful for pausing on content sections.
`scroll_by`	integer (px)	`1000`	Pixels to scroll per step.
`scroll_start_immediately`	boolean	`true`	Start scrolling immediately or wait for `scroll_delay` first.
`scroll_start_delay`	integer (ms)	`0`	Wait time before the first scroll begins.
`scroll_back`	boolean	`true`	Scroll back up after reaching the bottom of the page.
`scroll_back_algorithm`	string	`once`	`once` = smooth scroll up with easing. `repeat` = reverse the scroll-down steps.
`scroll_back_after_duration`	integer (ms)	--	Start scrolling back after this duration (instead of immediately).
`scroll_complete`	boolean	`true`	Stop recording when the scroll animation completes.
`scroll_stop_after_duration`	integer (ms)	--	Stop scrolling after this duration regardless of position.
`scroll_easing`	string	`ease_in_out_quint`	Easing function for the scroll animation. See table below.
`scroll_till_selector`	string (CSS)	--	Scroll until this CSS selector becomes visible instead of scrolling to the bottom.
`scroll_till_selector_adjust_top`	integer	--	Vertical offset when scrolling to the target selector.
`scroll_to_end_after`	integer (ms)	--	Jump to the bottom after this duration in one smooth motion with easing.

You can trigger a page navigation mid-scroll to show multiple pages in a single video.

Parameter	Type	Default	Description
`scroll_try_navigate`	boolean	--	Navigate to a new page during the scroll recording.
`scroll_navigate_after`	integer (ms)	duration / 2	When to trigger the navigation.
`scroll_navigate_to_url`	string	--	Destination URL for navigation.
`scroll_navigate_link_hints`	string[]	`["pricing", "about", "customers"]`	Keywords to match link text for auto-navigation.

Easing Functions

Available values for scroll_easing:

Function	Description
`linear`	Constant speed throughout the animation
`ease_in_quad`	Gradual acceleration (quadratic)
`ease_out_quad`	Gradual deceleration (quadratic)
`ease_in_out_quad`	Acceleration then deceleration (quadratic)
`ease_in_cubic`	Gradual acceleration (cubic)
`ease_out_cubic`	Gradual deceleration (cubic)
`ease_in_out_cubic`	Acceleration then deceleration (cubic)
`ease_in_quart`	Gradual acceleration (quartic)
`ease_out_quart`	Gradual deceleration (quartic)
`ease_in_out_quart`	Acceleration then deceleration (quartic)
`ease_in_quint`	Gradual acceleration (quintic)
`ease_out_quint`	Gradual deceleration (quintic)
`ease_in_out_quint`	Acceleration then deceleration (quintic) -- default

Tip: ease_in_out_cubic is a good all-purpose choice. It feels natural without being too slow at the start or end. Use linear when you need constant-speed scrolling for technical recordings.

Code Examples

cURL

bash

# Basic scroll animation as MP4
curl "https://api.nodium.io/api/v1/screenshot/animate?access_key=YOUR_API_KEY&url=https://example.com&format=mp4&scenario=scroll" \
  -o scroll.mp4

# GIF with custom scroll settings
curl "https://api.nodium.io/api/v1/screenshot/animate?access_key=YOUR_API_KEY&url=https://example.com&format=gif&scenario=scroll&duration=8&scroll_easing=ease_in_out_cubic&scroll_back=true" \
  -o scroll.gif

# High-quality MP4 with full control
curl -X POST "https://api.nodium.io/api/v1/screenshot/animate" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "format": "mp4",
    "scenario": "scroll",
    "duration": 15,
    "scroll_by": 500,
    "scroll_duration": 2000,
    "scroll_delay": 300,
    "scroll_back": true,
    "scroll_easing": "ease_in_out_quint",
    "viewport_width": 1920,
    "viewport_height": 1080
  }' -o video.mp4

Node.js

javascript

const fs = require("fs");

async function recordScrollVideo() {
  const response = await fetch(
    "https://api.nodium.io/api/v1/screenshot/animate",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Key": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        url: "https://example.com",
        format: "mp4",
        scenario: "scroll",
        duration: 10,
        scroll_duration: 2000,
        scroll_delay: 500,
        scroll_easing: "ease_in_out_cubic",
        scroll_back: true,
        viewport_width: 1280,
        viewport_height: 720,
      }),
    }
  );

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

  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync("scroll-video.mp4", buffer);
  console.log("Video saved!");
}

recordScrollVideo();

Python

python

import requests

response = requests.post(
    "https://api.nodium.io/api/v1/screenshot/animate",
    headers={"X-Access-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "format": "gif",
        "scenario": "scroll",
        "duration": 8,
        "scroll_duration": 1500,
        "scroll_delay": 400,
        "scroll_easing": "ease_in_out_cubic",
        "scroll_back": True,
        "viewport_width": 800,
        "viewport_height": 600,
    },
)

if response.status_code == 200:
    with open("scroll.gif", "wb") as f:
        f.write(response.content)
    print("GIF saved!")
else:
    error = response.json()
    print(f"Error: {error['error_code']} - {error['message']}")

Tips for Optimal Quality

File Size

Use mp4 or webm for the smallest file sizes. GIF files are significantly larger for the same duration and resolution.
Reduce duration to the minimum needed. A 5--8 second scroll is usually sufficient for most pages.
Lower the resolution with width and height or aspect_ratio if the video is for social media or thumbnails.
Use scroll_complete=true (default) to stop recording as soon as the scroll finishes, avoiding unnecessary frames.

Smoothness

Increase scroll_duration for smoother, slower scrolling. Values between 1500--3000ms work well.
Reduce scroll_by to scroll smaller distances per step, creating a more gradual reveal.
Use ease_in_out_cubic or ease_in_out_quint for natural-feeling scroll motion.
Add scroll_start_delay of 500--1000ms to give viewers a moment to orient themselves before scrolling begins.

Content Loading

Pair with wait_until=networkidle0 to ensure all page content is loaded before recording starts.
Use delay to add extra wait time for JavaScript-heavy pages.
Enable block_ads=true and block_cookie_banners=true for cleaner recordings.

Combining with Other Options

The /animate endpoint accepts all parameters from /take. Here are some powerful combinations:

bash

# Dark mode scroll video with ad blocking
curl -X POST "https://api.nodium.io/api/v1/screenshot/animate" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "mp4",
    "scenario": "scroll",
    "duration": 10,
    "dark_mode": true,
    "block_ads": true,
    "block_cookie_banners": true,
    "viewport_width": 1920,
    "viewport_height": 1080
  }' -o dark-scroll.mp4

# Mobile device scroll animation
curl -X POST "https://api.nodium.io/api/v1/screenshot/animate" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "gif",
    "scenario": "scroll",
    "duration": 6,
    "viewport_device": "iphone_16_pro",
    "scroll_easing": "ease_in_out_cubic"
  }' -o mobile-scroll.gif

# Transparent background video (MOV only)
curl -X POST "https://api.nodium.io/api/v1/screenshot/animate" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "mov",
    "scenario": "scroll",
    "omit_background": true,
    "duration": 8
  }' -o transparent-scroll.mov

# Async video with webhook delivery
curl -X POST "https://api.nodium.io/api/v1/screenshot/animate" \
  -H "X-Access-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "mp4",
    "scenario": "scroll",
    "duration": 15,
    "async": true,
    "webhook_url": "https://hooks.example.com/video-ready"
  }'

Note: For long-duration recordings (over 30 seconds of combined page load and capture time), use async=true to avoid timeout errors. See Async & Webhooks for details.

Screenshot -- Animated Screenshots & Videos

Table of Contents

What Are Animated Screenshots?

Endpoint

`GET/POST /animate` -- Animated Screenshot / Video

Video Formats

Parameters

Core Animation

Scroll Animation

Navigation During Scroll

Easing Functions

Code Examples

cURL

Node.js

Python

Tips for Optimal Quality

File Size

Smoothness

Content Loading

Combining with Other Options

Screenshot -- Animated Screenshots & Videos

Table of Contents

What Are Animated Screenshots?

Endpoint

GET/POST /animate -- Animated Screenshot / Video

Video Formats

Parameters

Core Animation

Scroll Animation

Navigation During Scroll

Easing Functions

Code Examples

cURL

Node.js

Python

Tips for Optimal Quality

File Size

Smoothness

Content Loading

Combining with Other Options

`GET/POST /animate` -- Animated Screenshot / Video