Website screenshots

Capture any public URL - viewport, full page, signed PNG or JPEG.

← All Website Screenshots endpoints · Capability overview

POST/v1/website-screenshots/screenshot

https://api.vee3.io/v1/website-screenshots/screenshot

20 tokens

Capture any public URL - viewport, full page, signed PNG or JPEG.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

website-screenshots.capture

Parameters11 fields

urlstringRequired

Public http or https URL to capture. Private, localhost, and internal network addresses are blocked.

max length 2048

full_pagebooleanOptional

Capture the full scrollable page. When false, only the viewport area is captured.

Default: false

viewport_widthintegerOptional

Browser viewport width in pixels.

Default: 1280 · min 320, max 3840

viewport_heightintegerOptional

Browser viewport height in pixels.

Default: 720 · min 240, max 2160

wait_until"load" | "domcontentloaded" | "networkidle"Optional

When to take the screenshot: 'load' (load event), 'domcontentloaded' (DOM ready, faster), or 'networkidle' (no network activity for 500ms, slowest but most complete).

Default: "domcontentloaded"

timeout_secondsintegerOptional

Maximum seconds to wait for the page to load before failing.

Default: 30 · min 5, max 60

format"png" | "jpeg"Optional

Output image format. 'png' preserves lossless quality (default). 'jpeg' produces smaller files.

Default: "png"

qualityintegerOptional

JPEG compression quality from 0 (smallest) to 100 (best). Only applies when format is 'jpeg'; ignored for PNG.

Default: 80 · min 0, max 100

dark_modebooleanOptional

When true, emulate prefers-color-scheme: dark so sites with dark-mode CSS render in dark mode. Has no effect on sites without dark-mode styling.

Default: false

block_cookie_bannersbooleanOptional

When true, attempt to dismiss common cookie consent banners and overlays before capture. Best-effort - custom or first-party banners may remain.

Default: false

file_namestringOptional

Optional account-relative storage path for the screenshot. If omitted, the file is stored under downloads/ with a generated name.

max length 255

Response21 fields

screenshot_idstring

Unique identifier, prefix ss_.

statusstring

Always "completed" for synchronous capture.

urlstring

Echo of requested URL.

screenshot_urlstring

Signed download URL from account file storage.

file_namestring

Account-relative path where the screenshot was stored.

viewport_widthinteger

Actual viewport width used.

viewport_heightinteger

Actual viewport height used.

full_pageboolean

Whether full page was captured.

dark_modeboolean

Echo of whether dark color scheme emulation was used.

block_cookie_bannersboolean

Echo of whether cookie banner dismissal was attempted.

formatenum

Echo of the requested output format (png or jpeg).

qualityinteger

Echo of JPEG quality used when format is jpeg.

file_size_bytesinteger

Image file size in bytes.

retained_untilstring

ISO 8601 timestamp when account storage retention expires.

created_atstring

ISO 8601 timestamp.

download_codestring

Short code to pass to the @vee3/cli `vee3-get-file` command.

download_idstring

Stable identifier for the reserved download.

expires_atstring

ISO 8601 timestamp when the download code can no longer be resolved (60 minutes after reserve).

install_commandstring

One-time command to install the Vee3 CLI (`npm install -g @vee3/cli`). On networks that inspect HTTPS, install may require Node 22.15+ with NODE_OPTIONS=--use-system-ca.

commandstring

Suggested terminal command for downloading to a local path.

troubleshootingstring

What to do if installation or downloading fails: re-read this tool's description via meta-tools.describe for setup and troubleshooting steps.

HTTP errors: unauthorized, url_blocked, screenshot_timeout, validation_error, site_unreachable, insufficient_tokens, payment_required, uploaded_file_name_in_use

Example request

Python

import requests

url = "https://api.vee3.io/v1/website-screenshots/screenshot"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "url": "https://example.com",
    "wait_until": "domcontentloaded"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Screenshot saved to account file storage with signed URL and download code.

stored_screenshot.json

{
  "screenshot_id": "ss_example01abcdef12",
  "status": "completed",
  "url": "https://example.com",
  "screenshot_url": "https://f000.backblazeb2.com/file/vee3-user-uploads/acct/downloads/ss_example01abcdef12.png?Authorization=...",
  "file_name": "downloads/ss_example01abcdef12.png",
  "viewport_width": 1280,
  "viewport_height": 720,
  "full_page": false,
  "dark_mode": false,
  "block_cookie_banners": false,
  "format": "png",
  "file_size_bytes": 248516,
  "retained_until": "2026-05-28T12:00:00Z",
  "created_at": "2026-05-26T12:00:00Z",
  "download_code": "bK3mP9x2",
  "download_id": "4feacf05-aae6-5e9a-97c4-9edfcd756306",
  "expires_at": "2026-05-26T13:00:00Z",
  "install_command": "npm install -g @vee3/cli",
  "command": "vee3-get-file bK3mP9x2 ./path/to/save",
  "troubleshooting": "If installation or downloading fails, call meta-tools.describe with tool_name 'website-screenshots.capture' and follow its setup and troubleshooting notes."
}