How to capture a webpage as WebP using a screenshot API

To capture a webpage as WebP, use a screenshot API that documents WebP output, send the page’s absolute URL, and explicitly set its format to webp. Then handle the response in the form that API documents: it may be raw image bytes, a redirect, or JSON containing an image URL. Save raw bytes with a .webp extension; do not assume that every screenshot API returns an image file directly.

This guide shows the request pattern, explains response handling and capture settings, and covers common failure cases. API parameter names, authentication, defaults, limits, and response formats vary by provider. Check the selected provider’s current documentation before adapting the examples.

1. Choose a WebP-capable screenshot endpoint

Confirm that the provider explicitly supports WebP as a screenshot output format. Do not infer support from the fact that the service returns images, and do not rely on its default format: some endpoints default to PNG.

Before integrating, confirm these details in the provider’s documentation:

• The supported HTTP method and endpoint path.
• How to authenticate, and whether credentials belong in a header or query parameter.
• The exact spelling and accepted values for the format and quality fields.
• Whether the response is raw bytes, a redirect, or JSON containing a URL.
• Viewport, full-page, timeout, dimension, and quota limits.

For example, Screenshot API documents GET and POST screenshot endpoints and a format option. Its documentation describes bearer-token and API-key header options, as well as a query-key option. Webstractor documents a GET route that returns raw image bytes and supports WebP or PNG. These are examples of provider-specific contracts, not interchangeable request syntax: Screenshot API documentation and Webstractor documentation.

2. Make the request and handle the response

The following request is schematic. It combines a documented Screenshot API POST path and format field with a quality setting shown in its documentation; adapt the path, authentication, field names, and response handling to the provider you choose. The example assumes the endpoint returns raw image bytes.

POST /api/v1/screenshot
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"url":"https://example.com","format":"webp","quality":80}

If the endpoint returns raw bytes, check for a successful HTTP status and an image content type before saving the body as screenshot.webp. If it returns JSON, parse the documented image URL field and retrieve that URL. If it redirects, follow the redirect according to the provider’s documentation. A filename ending in .webp does not convert another image format into WebP.

cURL: save a raw-byte response

This version assumes a POST endpoint that returns image bytes. Use the provider’s documented URL, field names, and authentication scheme.

curl --fail --location \
  --request POST "https://provider.example/api/v1/screenshot" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com","format":"webp","quality":80}' \
  --output screenshot.webp

--fail makes cURL return an error for HTTP error responses rather than quietly writing an error body as an image. --location follows redirects. Keep API keys out of shared scripts and public repositories; use your deployment’s secret-management mechanism.

Python: check status and save bytes

import requests

endpoint = "https://provider.example/api/v1/screenshot"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
    "url": "https://example.com",
    "format": "webp",
    "quality": 80,
}

response = requests.post(
    endpoint,
    headers=headers,
    json=payload,
    timeout=90,
)
response.raise_for_status()

content_type = response.headers.get("Content-Type", "").lower()
if "image/" not in content_type:
    raise ValueError(f"Expected image bytes; received Content-Type: {content_type!r}")

with open("screenshot.webp", "wb") as image_file:
    image_file.write(response.content)

This code expects raw image bytes. If the provider returns JSON or a redirect to a hosted image, implement that documented response flow instead of writing the JSON body to a file.

Node.js: check status and save bytes

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

const endpoint = 'https://provider.example/api/v1/screenshot';
const res = await fetch(endpoint, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'webp',
    quality: 80,
  }),
  signal: AbortSignal.timeout(90_000),
});

if (!res.ok) {
  throw new Error(`Screenshot request failed: HTTP ${res.status}`);
}

const contentType = res.headers.get('content-type') ?? '';
if (!contentType.toLowerCase().startsWith('image/')) {
  throw new Error(`Expected image bytes; received Content-Type: ${contentType}`);
}

await writeFile('screenshot.webp', Buffer.from(await res.arrayBuffer()));

This uses Node.js’s built-in fetch and assumes the endpoint returns image bytes. For a JSON response, parse it with await res.json() and follow the returned image URL as the provider specifies.

3. Set capture options for the intended image

WebP only determines the encoded output format. It does not determine what the browser renders or which part of the page is captured. Set capture options deliberately, using the names and limits documented by the selected API.

Setting	What it affects	What to check
Viewport width and height	Responsive layout, text wrapping, and visible area	Specify dimensions matching the intended display or test breakpoint.
Full-page capture	Whether the image covers content below the initial viewport	Check maximum page height and how the provider handles sticky elements and long pages.
Wait strategy	Whether the page has rendered enough before capture	Use a documented selector wait, delay, or network-idle option when needed.
Element selector	Whether the output is one component rather than the whole page	Confirm the selector exists at capture time and is unique enough for the page.
Device scale	Pixel density and output dimensions	Check whether the provider calls this scale, device scale factor, or another name.
WebP quality	File size and lossy image detail, where supported	Use only the provider’s documented range and test the result on the target content.

Quality values are provider-specific. Screenshot API documents JPEG/WebP quality from 1 to 100; Webstractor documents a WebP default quality of 82. Those values describe those vendors’ APIs and are not a shared standard or a universal recommendation. Check the current documentation for Screenshot API or Webstractor before relying on a value.

4. Verify the saved image

1. Check that the request succeeded and the response matches the provider’s documented output type.
2. Confirm that the file is non-empty and opens in a WebP-capable viewer or image library.
3. Inspect the rendered page at the chosen viewport, including fonts, images, and dynamic content.
4. Compare dimensions and file size against the needs of the destination, such as a thumbnail, report, or visual regression check.
5. If the result is not actually WebP, revisit the requested format and response contract. Renaming a PNG file does not encode it as WebP.

5. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Send one GET request with a URL and request WebP output. See the ScreenshotNeo API documentation for the current parameter details.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: HTTP ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) =>
  writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))
);

• Cookie banners are accepted and removed before capture; 60+ known consent platforms, newsletter popups, and chat widgets can be removed, with each step configurable.
• Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses include X-Page-Verdict and X-Billed headers.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
• The free plan includes 1,000 shots per month without a card. Paid plans start at $5 for 3,000 shots.

Sign up for ScreenshotNeo and get 1,000 screenshots a month free, with no card required.

6. Troubleshooting

Symptom	Likely cause	Fix
The saved file is JSON or an error page	The API returned an error body, JSON, or a URL response instead of image bytes.	Check the HTTP status and Content-Type. Handle the documented response type; do not save a JSON body with a WebP filename.
The image is PNG or JPEG	The format was omitted, misspelled, unsupported, or ignored because the provider uses another field or endpoint.	Confirm WebP support and the exact format parameter in current API docs. Inspect the response content type.
The file is empty or truncated	The request failed, timed out, or the body was not fully read.	Check status before saving, configure a suitable timeout, and retry transient failures with a bounded retry policy.
The page looks unfinished	Capture occurred before client-side rendering, images, or fonts finished loading.	Use a provider-supported wait condition, selector wait, delay, or network-idle setting; avoid an unnecessarily long fixed delay.
The layout differs from the browser	The capture viewport, device scale, user agent, or page state differs from the expected environment.	Set the documented viewport and scale, and provide required cookies or headers if supported and appropriate.
A full-page image is clipped	The provider enforces a height or dimension limit, or the page uses unusual scrolling behavior.	Check full-page limits and try a supported element capture or smaller viewport/page region.
Authentication fails	The key is missing, invalid, expired, or sent using the wrong mechanism.	Use the provider’s documented header or query parameter and confirm the key is available to the running process.
Request succeeds but produces unexpected cost	Billing rules, cache behavior, or failed-page handling differ by provider.	Read current plan and billing documentation; use provider response headers or usage endpoints where available.

7. Performance, reliability, and cost

Capture latency depends on page rendering, network activity, wait conditions, and image dimensions. Full-page captures and pages with heavy client-side rendering can take longer or consume more resources than a viewport capture. Use a request timeout appropriate to the provider’s documented limits, and avoid waiting for network idle on pages that keep long-lived requests open if another documented wait strategy fits better.

For a production workflow, distinguish transient transport errors from permanent failures such as invalid URLs or authentication. Retry only errors that may resolve on a later attempt, cap retries, and avoid retry storms. If your application processes many pages, use documented concurrency, quota, and asynchronous-job limits. Confirm how the provider bills failed captures, cache hits, and retries; the available comparative research does not establish general prices, quotas, or reliability across vendors.

WebP can be useful when the consuming system accepts it and smaller image payloads matter, but the resulting size and visual quality depend on page content and the provider’s encoding settings. Inspect actual outputs for text-heavy pages, gradients, and fine details. Avoid treating one vendor’s quality value as portable to another API.

8. Frequently asked questions

Does every screenshot API support WebP?

No. Check the selected endpoint’s current documentation and request WebP explicitly if it is supported.

Can I make a PNG screenshot into WebP by changing the filename?

No. A file extension does not change the encoding. Request WebP from the screenshot service or run a separate image conversion step.

Can I use the resulting WebP in an HTML image element?

Yes, if the browser and delivery path support WebP and the server sends an appropriate image content type. For public image embedding, use an output URL or signed-link feature only if the provider documents one.

Is quality 80 the right setting?

There is no provider-independent answer. Quality ranges and defaults vary; follow the selected service’s documentation and inspect the output for your use case.