How to Capture a Webpage Screenshot with a Transparent Background Using an API
Capture transparent webpage screenshots with Playwright or Puppeteer, understand what omitBackground changes, and choose a hosted API when you want to skip browser setup.
To capture a webpage screenshot with a transparent background using a browser automation API, set omitBackground: true and save as PNG. In Playwright, use await page.screenshot({ path: 'capture.png', omitBackground: true }); Puppeteer supports the same option. This removes the browser renderer’s default white background. It does not erase a background color or image that the webpage itself paints. Playwright documents that omitBackground does not apply to JPEG, so PNG is the safest starting format for transparency.
If by “API” you mean a hosted screenshot service, its parameters are provider-specific. Do not assume it accepts Playwright’s omitBackground option by that name. ScreenshotNeo provides a transparent-background option; see its API documentation for the current request parameters. ScreenshotNeo is a website screenshot API and MCP server from Yorker Media.
1. Capture a transparent screenshot with Playwright
Install Playwright and its Chromium browser, then run this Node.js example. It navigates to a page, takes a PNG screenshot with the renderer’s default background omitted, and writes the result to disk.
npm install playwright
npx playwright install chromium// screenshot.mjs
import { chromium } from 'playwright';
const targetUrl = process.argv[2] ?? 'https://example.com';
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
await page.goto(targetUrl, { waitUntil: 'load', timeout: 30_000 });
await page.screenshot({
path: 'capture.png',
type: 'png',
omitBackground: true
});
} finally {
await browser.close();
}Run it with node screenshot.mjs https://example.com. The example waits for the page load event, but that is only a starting point: applications that render content after navigation may need a selector-based wait or another readiness condition.
Wait for the content you need
There is no universally correct wait condition for every site. If the content appears after a client-side request, wait for a meaningful element rather than adding an arbitrary long delay:
await page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30_000 });
await page.locator('[data-report-ready="true"]').waitFor({ timeout: 15_000 });
await page.screenshot({ path: 'capture.png', type: 'png', omitBackground: true });Replace the selector with one that exists when the part of the page you want is ready. A fixed delay can help when a site has a known animation or delayed render, but it makes every capture wait even when the page is ready sooner.
2. Capture a transparent screenshot with Puppeteer
Puppeteer uses the same omitBackground: true setting. Install Puppeteer, which downloads a compatible browser by default, and save a PNG:
npm install puppeteer// screenshot-puppeteer.mjs
import puppeteer from 'puppeteer';
const targetUrl = process.argv[2] ?? 'https://example.com';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setViewport({ width: 1440, height: 1000 });
await page.goto(targetUrl, { waitUntil: 'load', timeout: 30_000 });
await page.screenshot({
path: 'capture.png',
type: 'png',
omitBackground: true
});
} finally {
await browser.close();
}Run with node screenshot-puppeteer.mjs https://example.com. Puppeteer documents fullPage and clip for capture scope as well. The transparency setting controls the renderer’s default background, not the website’s own CSS.
3. Control the capture area and image format
Transparency, capture scope, and output format are separate choices. Playwright’s screenshot API documents PNG, JPEG, and WebP types; its omitBackground option is not applicable to JPEG. Use PNG when transparent pixels are required, and verify the file in the application that will consume it.
| Need | Setting | Notes |
|---|---|---|
| Transparent renderer background | omitBackground: true |
Use PNG. Does not remove backgrounds painted by page CSS. |
| Whole scrollable page | fullPage: true |
Captures beyond the current viewport; long pages can produce large images. |
| Specific rectangle | clip: { x, y, width, height } |
Coordinates define the area to capture. Keep the clip within the rendered page. |
| Output format | type: 'png', 'jpeg', or 'webp' in Playwright |
For transparency, PNG is the direct documented choice. JPEG does not support this option. |
For example, combine a full-page capture with transparency in Playwright:
await page.screenshot({
path: 'full-page.png',
type: 'png',
omitBackground: true,
fullPage: true
});Or capture a region:
await page.screenshot({
path: 'region.png',
type: 'png',
omitBackground: true,
clip: { x: 100, y: 120, width: 800, height: 600 }
});Both Playwright and Puppeteer document full-page and clipped capture controls. Check the selected library’s current API reference for all option details: Playwright Page API, Puppeteer ScreenshotOptions, and the Puppeteer screenshots guide.
4. Why the screenshot may still have a background
omitBackground hides the browser’s default white canvas. A page can still appear opaque if its own styles paint a background on the body, a wrapper, or another element. A CSS background image also remains page content; the option does not remove it.
If you own the page and need its authored background removed, change that page’s styles intentionally before capture. For a one-off Playwright capture, the screenshot API supports a style option that applies styles while capturing:
await page.screenshot({
path: 'capture.png',
type: 'png',
omitBackground: true,
style: 'html, body { background: transparent !important; }'
});This example targets the document background only. Other elements may still paint their own backgrounds, so identify and adjust the specific selectors that are responsible. Puppeteer users can apply the required page styles before calling screenshot.
5. Hosted screenshot APIs and cURL, Python, and Node.js
A hosted screenshot API runs the browser capture for you. Its request contract determines the endpoint, authentication, output format, and transparency parameter. The Playwright and Puppeteer references establish the browser-library option; they do not establish a universal hosted API parameter. Consult the chosen provider’s documentation rather than sending omitBackground blindly.
ScreenshotNeo request examples
ScreenshotNeo accepts a URL and returns a screenshot or PDF. Set its transparent-background option as described in the ScreenshotNeo API docs. The examples below show the basic one-request capture pattern; they do not include an undocumented transparency parameter.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpPython
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)Node.js
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: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) =>
writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))
);These examples capture the supplied URL. To request transparency, add the documented ScreenshotNeo option for that feature and choose a supported transparent output format in the current docs. The returned image’s behavior depends on the requested format and the page’s own painted backgrounds.
Or skip the browser setup
Use ScreenshotNeo’s one-call API and configure transparent output using its documented option:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpCookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
6. Validate transparency and avoid common capture problems
- Inspect the alpha channel. Open the PNG in an editor that displays transparency or inspect it with your image-processing tools. A white-looking preview alone does not prove the PNG lacks alpha; some viewers display transparent areas on white.
- Check the page’s CSS. If the alpha is opaque where the page has a background, inspect the body and element backgrounds.
omitBackgrounddoes not erase those styles. - Check the format. Use PNG for Playwright transparency. Playwright explicitly says the option is not applicable to JPEG.
- Check capture readiness. If expected content is missing, wait for a selector or the site-specific event that means the content is ready.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Background still looks white | The page paints a white background in CSS, or the viewer displays transparency as white. | Inspect the alpha channel. If the page itself paints white, adjust the relevant CSS before capture. |
| JPEG has no transparency | Playwright’s omitBackground is not applicable to JPEG. |
Capture PNG and use it in a consumer that preserves alpha. |
| ScreenshotNeo request rejects an option | A Playwright option name may not be a hosted API parameter. | Use the current provider documentation to find the supported parameter name and format. |
| Capture is blank or content is missing | The page’s required content was not ready at screenshot time, or navigation did not complete as expected. | Wait for a meaningful selector or site-specific readiness condition; handle navigation errors and timeouts. |
| Full-page capture is unexpectedly large | The page is long or contains large rendered regions. | Capture a clip or viewport when full-page output is not required; select an output size appropriate for the consumer. |
| Clip misses the desired content | The clip coordinates or dimensions do not match the page’s rendered layout. | Check the viewport and element position, then adjust the clip rectangle. |
7. Performance, reliability, and cost considerations
With Playwright or Puppeteer, each capture requires a browser page to navigate and render. Reusing a browser process for multiple captures can avoid repeatedly starting the browser, while closing pages after use limits accumulated resources. These are implementation considerations, not benchmark claims. Keep navigation and readiness timeouts bounded, and wait for the specific content your capture needs so a slow third-party request does not hold up every screenshot.
Full-page captures can require more rendering and produce larger files than a viewport or clip. Choose the smallest capture area and output dimensions that meet the use case. PNG is the documented transparency path, though the resulting file size depends on page content and dimensions.
Self-hosting means you operate the browser runtime and handle its failures, updates, and capacity. A hosted service removes that browser setup but introduces provider-specific request rules and pricing. ScreenshotNeo bills only clean shots: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its plans are Free (1,000 shots/month, no card), Starter ($5 for 3,000), Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000), and Business ($249 for 1,000,000); yearly billing gives two months free. Every feature is on every plan.
8. Frequently asked questions
How do I capture a webpage screenshot with a transparent background?
In Playwright or Puppeteer, set omitBackground: true and save as PNG. Also check whether the page’s own CSS paints a background.
Can a screenshot API return a transparent PNG?
That depends on the hosted provider’s supported formats and parameters. Check its current API contract. ScreenshotNeo supports a transparent-background option; consult its docs for the exact request configuration.
Does transparent capture remove the website background image?
No. The browser option removes its default white background, not images or colors painted by the page.
Can I use JPEG for a transparent screenshot?
Not with Playwright’s omitBackground option, which its API marks as not applicable to JPEG. Use PNG for the documented transparent capture path.
Can I capture only one element or the whole page?
Playwright and Puppeteer provide capture-scope options such as clipping and full-page capture. These scope controls are separate from the transparent-background setting.
