Website Screenshot API That Exports PDF and Full-Page Images

A website screenshot API opens a URL in a hosted browser, applies capture settings, and returns an image or PDF. For a full-page image, enable the provider’s full-page option; for a PDF, select PDF output and configure paper size, orientation, margins, and print backgrounds where supported. Parameters differ by provider, so use that provider’s current API reference rather than assuming names are interchangeable.

ScreenshotNeo is one option for URL or HTML input and PNG, JPEG, WebP, or PDF output. This guide explains how to choose a service, build requests, handle long or dynamic pages, and diagnose common failures.

1. What a screenshot API does

A screenshot API renders a page in a browser environment and returns a file or a link to one. Your application sends a public URL, capture settings, and credentials. The service loads the page, waits according to its rendering rules, then captures the viewport, full page, selected element, or PDF. This hosted workflow differs from taking a screenshot manually on a local device.

Some APIs also accept HTML directly. That is useful for rendering generated documents or social preview cards without publishing a page first. Check input size limits and whether HTML is submitted through a POST body.

2. Choose an API by output and control

Start with the file you need and the conditions under which it must be captured. PNG is lossless and useful for crisp UI details; JPEG and WebP offer quality controls on some services; PDF is intended for paginated documents and printing. Verify the precise formats, quality settings, response type, and retention behavior in the provider’s own documentation.

Decision	What to check	Why it matters
Output	PNG, JPEG/JPG, WebP, and PDF availability; compression quality	Formats and quality controls differ between services.
Capture area	Viewport, full page, element selector, or clipping rectangle	Full-page implementations vary; very long pages and lazy content need special handling.
Rendering	Viewport dimensions, device scale, mobile emulation, dark mode, wait strategy	These settings affect responsive layout and the final pixels.
PDF	Paper size, orientation, margins, page ranges, printed backgrounds	Browser print output can differ from an image capture.
Integration	Authentication, direct bytes vs URL/JSON, async jobs, batch support, retention	Choose a response workflow your application can safely store and retry.
Cost and reliability	Quota, concurrency, rate limits, cache behavior, failure billing, support terms	Vendor claims are not independent evidence of performance or reliability.

Documented examples include Screenshot API, which documents a fullPage option and PDF support, and RelayPDF, which describes a URL/HTML image endpoint with full-page controls and a separate PDF flow. GetScreenshot documents PNG/JPEG/WebP captures, PDF generation, viewport controls, and PDF page controls. These are vendor-described capabilities, not independent comparative test results. ScreenshotNeo comes first as a product to consider because it cleans cookie banners, popups, and chat widgets before capture and bills only clean shots.

3. Integrate a full-page screenshot and PDF endpoint

The examples below use ScreenshotNeo so that the image and PDF calls share the same endpoint and options. Create an API key first, keep it on the server, and follow the ScreenshotNeo API documentation for the full parameter reference. Replace the target URL as needed.

cURL: save a full-page WebP

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -d format=webp \
  -d full_page=true \
  -o stripe.webp

Python: save a full-page WebP

import requests

response = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://stripe.com",
        "format": "webp",
        "full_page": "true",
    },
    timeout=90,
)
response.raise_for_status()
with open("stripe.webp", "wb") as output:
    output.write(response.content)

Node.js: save a full-page WebP

import { writeFile } from "node:fs/promises";

const q = new URLSearchParams({
  access_key: "YOUR_API_KEY",
  url: "https://stripe.com",
  format: "webp",
  full_page: "true",
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await writeFile("stripe.webp", Buffer.from(await res.arrayBuffer()));

PDF output

Change the output format to pdf. Set the paper and print settings explicitly when the document has layout requirements.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -d format=pdf \
  -d pdf_paper=a4 \
  -d pdf_landscape=false \
  -d pdf_background=true \
  -d pdf_margin=10mm \
  -o stripe.pdf

The API’s documented PDF controls include A3, A4, A5, Letter, Legal, and Tabloid paper, landscape orientation, printed backgrounds, margins in px/mm/cm/in, and page ranges such as 1-3,5. Browser-generated PDF layout depends on the page’s print CSS; use media_type=print when print styles are the intended design, and inspect pagination for clipped or split content.

POST requests for HTML and structured options

Use POST when sending raw HTML or when a structured request is easier to maintain. ScreenshotNeo documents HTML input up to 2 MB. Keep credentials out of browser-side code; send them from a trusted server.

curl -X POST "https://api.screenshotneo.com/v1/shot" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com",
    "format": "png",
    "full_page": true,
    "full_page_scroll": true,
    "wait_until": "networkidle2",
    "timeout": 60
  }' \
  -o stripe.png

For direct file responses, write the response bytes to a file as in the examples. Some other APIs return JSON metadata or a temporary file URL by default; inspect status and content type rather than assuming every successful response is image bytes.

4. Configure capture behavior

Full-page, viewport, and element capture

• Viewport capture: Set width and height to the CSS viewport you want. This is usually the right choice for a hero image or a fixed visual regression target.
• Full page: Set full_page=true. With ScreenshotNeo, full_page_scroll=true scrolls down first so lazy-loaded images and sections can appear. full_page_max_height can cap output height from 500 to 16,000 pixels; this is useful for endless feeds.
• Element: Set selector to a CSS selector to capture the first matching element. A missing or unstable selector can fail; choose a selector that is specific and present after rendering.
• Rectangle: Use clip as x,y,width,height in CSS pixels when a known region is needed.

Formats, image size, and devices

ScreenshotNeo supports png, jpeg (also accepted as jpg), webp, and pdf. JPEG and WebP accept quality from 1–100. image_width and image_height resize output; when both are supplied, the image is cropped to fill both dimensions. Transparent backgrounds are available for PNG and WebP where the page itself has no background.

Choose a device preset or provide width and height directly. ScreenshotNeo documents desktop, laptop, full HD, MacBook Air, tablet, iPad Air, iPad Pro, mobile, iPhone 15, iPhone 15 Pro Max, Pixel 8, and Galaxy S24 presets. Width is 320–3840 CSS pixels, height 240–4320, and scale 1–3. A scale of 2 produces twice the pixel dimensions. Mobile mode, touch, and landscape can also be set independently.

Wait for dynamic content

A page’s initial HTML can arrive before its important content. Select a wait strategy based on the page:

• wait_until=load waits for the load event.
• wait_until=domcontentloaded is faster when the required content is already in the DOM.
• networkidle0 or networkidle2 waits for network activity to settle, but can be unsuitable for sites with long-lived connections.
• wait_for_selector waits for a specific element to appear, up to 20 seconds.
• delay adds up to 20 seconds after the selected load condition.

ScreenshotNeo’s default wait_until=auto uses the load event plus up to three seconds for the network to settle. Its timeout can be set from 5 to 90 seconds. Prefer waiting for the actual content selector over adding a large fixed delay; this usually makes the capture rule clearer and avoids unnecessary waiting.

Clean or customize the page

ScreenshotNeo enables handling for cookie and consent banners, popups, chat widgets, ads, and trackers by default; individual cleaning steps can be turned off. You can also hide selectors, inject CSS or JavaScript, click a selector before capture, block matching request URLs, or block resource types such as images, fonts, scripts, XHR, or WebSockets. Blocking resources can reduce work but may remove content needed for the desired image.

For localized or authenticated views, options include dark mode, reduced motion, print or screen media, user agent, accept-language, custom headers, cookies, authorization, timezone, latitude, and longitude. Custom headers and cookies are sent only to the target site according to the documentation. Avoid putting secrets in logs or publicly exposed query strings.

Response and automation options

• response_type=image returns the file; json returns file information and page metadata; empty returns headers only.
• cache=true retains results for 24 hours by default. cache_ttl can set a TTL up to 30 days; fresh=true requests a new render. Cache hits are not billed.
• async=true queues a job and returns a job ID. Poll the jobs endpoint or provide a webhook URL. Webhook delivery is signed and can retry, so validate signatures and deduplicate deliveries.
• POST /v1/bulk accepts up to 100 captures per call. Use the bulk status endpoint to collect results. A bulk job is billed per capture when it is a clean shot.
• GET /v1/usage reports plan and usage. Signed links support public image embedding without exposing a usable API key.

5. Make captures reliable and economical

Rendering time and output size depend on the target page and settings. Full-page captures, high device scale, large viewports, and resource-heavy pages require more work and produce larger files. Use the smallest viewport and image dimensions that satisfy the consumer. Prefer WebP or JPEG when lossy compression is acceptable; use PNG when exact pixel preservation matters. These are practical format tradeoffs, not measured comparative benchmarks.

Use caching for repeat requests whose contents do not need to be fresh. Set a TTL that matches how often the target changes, and use a cache key when logically different captures must not share an entry. For bursts or large batches, use async jobs or bulk capture, respect rate-limit responses, and retry transient failures with backoff. Do not retry invalid URLs or missing selectors without changing the request.

ScreenshotNeo reports verdict, billing, cache, render duration, remaining quota, page status, request ID, and ignored parameters in response headers. Log the request ID and verdict alongside your own job identifier. The vendor documents that bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; clean captures are billed. Full pages stop at 16,000 pixels, and pages that download more than 60 MB stop loading and are captured as they are.

6. Common errors and fixes

Error or symptom	Likely cause	Fix
400 bad_request	Missing parameter or value outside the allowed range	Read the named parameter and validate it against the API reference.
400/422 url_not_allowed	URL is not HTTP(S), is private/local/unresolvable, or redirects to a private address	Use a public, resolvable URL and check its redirect chain.
401 missing_or_invalid_key	Key omitted, mistyped, or revoked	Use a current key and send it through a server-side header or request.
402 quota_exceeded	Clean-shot quota is used up	Check the reset date and usage endpoint, then wait for reset or change plan.
403 signature or account error	Signed-request settings do not match, email is unverified, or account is disabled	Recreate the signature from the exact query string or address the account status.
422 bot_check	The site presented a bot challenge	Inspect the page verdict; consider an available share-image fallback where appropriate. Automated capture cannot guarantee access to a challenged page.
422 blank_page	The page rendered without usable content	Check the target URL and wait condition, then wait for a content selector or inspect the site behavior.
422 selector_not_found or script/content check error	Selector absent, injected script failed, or expected text missing	Confirm selectors against the rendered page and simplify or correct the script/check.
429 rate_limited or concurrency limit	Too many requests at once or too many per minute	Honor Retry-After, reduce concurrency, and queue large work asynchronously.
502 navigation/render failure; 504 timeout	Target could not be loaded or rendered before deadline	Check availability and redirects, relax overly strict network-idle waits, or increase timeout within the documented limit.
Image file is actually JSON	The provider returned an error or metadata response	Check HTTP status and content type before writing bytes; inspect the error body.
PDF has missing backgrounds or awkward page breaks	Print CSS, background settings, margins, or paper size do not match the intended document	Enable PDF backgrounds, set print media and paper explicitly, and adjust margins/page ranges.

7. ScreenshotNeo: skip the browser setup

Instead of managing a browser, call the hosted API. This cURL example returns a full-page WebP; use format=pdf for PDF output. See the ScreenshotNeo API documentation for capture parameters and response behavior.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -d format=webp -d full_page=true -o shot.webp

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000. It also supports PDF, async jobs, bulk capture, and 63 capture options. Create a free account and get 1,000 screenshots a month with no card.

8. Frequently asked questions

Can one API create both a full-page image and a PDF?

Some providers support both through one endpoint with an output parameter; others separate image and PDF endpoints. Verify this before integrating. ScreenshotNeo uses one /v1/shot endpoint for PNG, JPEG, WebP, and PDF.

Does full-page capture always include lazy-loaded images?

No. Full-page behavior varies. A service may need to scroll the page before capture so images and sections load. Check for a dedicated full-page scroll option and test pages with deferred content.

Can an API screenshot a private development site?

Do not assume so. ScreenshotNeo refuses private and internal addresses, including through redirects. For a private application, check whether the provider supports authenticated access through cookies or headers and whether its network access policy allows the host.

How should I compare API speed and image quality?

Vendor documentation alone does not establish an independent comparison. Define representative pages, output settings, and failure conditions, then evaluate candidates under your own requirements. Do not treat published vendor claims as comparable measurements.