Animations & scroll videos

POST /v1/animate — render a website to MP4, WebM, GIF (or MOV/AVI). Supports scrolling animations with 13 easings.

By default this endpoint is async (returns 202 + job_id immediately). Set "async": false to wait synchronously (max 90s).

Quickest example

curl https://websitescreenshotapi.net/api/v1/animate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com",
    "format": "mp4",
    "scenario": "scroll",
    "duration": 8,
    "scroll_back": true
  }'

Response (202 Accepted):

{
  "job_id":             "job_abc…",
  "db_id":              42,
  "status":             "queued",
  "status_url":         "https://websitescreenshotapi.net/api/v1/screenshot/42",
  "credits_charged":    8,
  "credits_remaining":  1992,
  "webhook_configured": false
}

Then poll GET /v1/screenshot/42 until status: "done", or pass a webhook_url for a callback.

Required

Field Type Notes
url string Target URL

Output options

Field Type Default Notes
format string mp4 mp4, webm, mov, avi, gif
duration int 1-30 sec 5 Total video length
viewport_width int 320-1920 1280
viewport_height int 240-1080 720
device_scale_factor float 1.0-2.0 1

Auto-duration (smart length)

Let the duration adapt to the page height — short pages get short videos, long pages get longer ones (capped).

Field Type Default Notes
auto_duration bool false Enable adaptive duration
max_duration int 1-30 sec 5 Cap (also used for billing — worst case)
scroll_speed_pps int 50-5000 400 Px / second of scroll. Lower = slower video.

Pricing in auto mode: max_duration is billed (worst case). The actual video may be shorter.

{
  "url": "https://yoursite.com",
  "format": "mp4",
  "scenario": "scroll",
  "auto_duration": true,
  "max_duration": 15,
  "scroll_speed_pps": 400
}

A 1200px page → 3s video, billed 15. A 8000px page → 15s video (capped), billed 15.

Scenarios

default — stand still

Records the page as-is after load. Useful for pages with intro animations or video backgrounds.

scroll — auto-scroll capture

Programmatically scrolls top→bottom while recording. Two modes:

Continuous (default) — single smooth tween from top to bottom over the full duration. Fluid 60fps.

{ "scenario": "scroll", "scroll_mode": "continuous", "duration": 10 }

Stepped (legacy) — scrolls in steps with pauses. Useful to "rythm" a demo.

{
  "scenario": "scroll",
  "scroll_mode": "stepped",
  "scroll_by": 500,
  "scroll_delay": 300,
  "scroll_duration": 1500
}

Scroll options

Field Type Default Notes
scroll_mode string continuous continuous or stepped
scroll_easing string ease_in_out_quint See easings below
scroll_start_delay int 0-10000 ms 0 Cooldown before scroll starts (lets CSS/lazy-load settle)
scroll_back bool true Smooth-scroll back to top at the end
scroll_back_duration int 200-5000 ms 1200 Time to scroll back

Stepped-only:

Field Type Default Notes
scroll_by int 50-5000 1000 Pixels per step
scroll_delay int 0-5000 ms 0 Pause between steps
scroll_duration int 100-5000 ms 1200 Animation time per step

Easings

13 supported (CSS-style cubic-bezier curves):

For demo-style smooth scroll, ease_in_out_quint is the prettiest. For natural reading speed, linear.

GIF tuning

Field Type Default Notes
gif_fps int 8-24 12 Frame rate. Higher = smoother + bigger
gif_width int 240-1280 720 Output width (height auto)

GIFs are encoded with a 2-pass palette pipeline (palettegen + paletteuse) for clean colors.

Webhook callback

Pass webhook_url (and optional webhook_secret) to receive a POST when the render completes. See Webhooks.

{
  "url": "https://yoursite.com",
  "format": "mp4",
  "duration": 10,
  "scenario": "scroll",
  "webhook_url":    "https://yoursite.com/wh/screenshot",
  "webhook_secret": "my-shared-secret-32-chars"
}

Cost

Videos are billed per second, with a minimum:

Format Rate Min Examples
MP4 / WebM / MOV / AVI 1 / sec 2 5s = 5, 10s = 10, 30s = 30
GIF 2 / sec 3 5s = 10, 10s = 20, 30s = 60

In auto_duration mode, max_duration is billed regardless of actual video length.