Running Puppeteer or Playwright yourself works until it doesn't: Chromium eats memory, cookie banners cover half the page, lazy-loaded images come out blank and a slow site ties up a worker for 30 seconds. A screenshot API moves that work off your servers. You send a URL, you get an image back.
This guide shows the same tasks in Node.js and Python with FastScreenshotAPI:
- Capture a page and save it to disk
- Get a hosted, signed URL instead of raw bytes
- Capture full pages, mobile views and PDFs
- Render your own HTML
- Run heavy captures as async jobs with signed webhooks
- Capture many URLs in one batch call
Everything below uses the real endpoint https://api.fastscreenshotapi.com/v1/screenshot and authenticates with the X-Api-Key header.
Get an API key
Create a free account and copy your key from the dashboard. The free plan includes 200 screenshots a month, no credit card required. Keep the key out of your code and read it from an environment variable:
export FASTSCREENSHOT_API_KEY="fsa_your_api_key"The API key belongs on your server. Don't ship it in browser JavaScript or a mobile app bundle; call the API from your backend instead.
1. Capture a page and save it
Send a POST with a JSON body. Set response_type to binary to get the image bytes back directly.
Node.js (18+)
Node 18 and newer ship fetch, so no dependencies are needed.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.fastscreenshotapi.com/v1/screenshot", {
method: "POST",
headers: {
"X-Api-Key": process.env.FASTSCREENSHOT_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com",
format: "png",
response_type: "binary",
}),
});
if (!response.ok) {
// Errors come back as JSON with a machine-readable code.
throw new Error(`Screenshot failed (${response.status}): ${await response.text()}`);
}
await writeFile("example.png", Buffer.from(await response.arrayBuffer()));
console.log("Saved example.png, cache:", response.headers.get("X-Cache"));Python
import os
import requests
response = requests.post(
"https://api.fastscreenshotapi.com/v1/screenshot",
headers={"X-Api-Key": os.environ["FASTSCREENSHOT_API_KEY"]},
json={
"url": "https://example.com",
"format": "png",
"response_type": "binary",
},
timeout=90,
)
response.raise_for_status()
with open("example.png", "wb") as f:
f.write(response.content)
print("Saved example.png, cache:", response.headers.get("X-Cache"))Every response carries X-Request-Id, X-Quota-Used and X-Quota-Limit headers, so you can log usage without a second call. Identical requests within the cache window return X-Cache: HIT and don't count against your quota.
2. Get a signed URL instead of bytes
If you are going to store the image or show it in a dashboard anyway, skip the upload step. The default response_type is url: we store the screenshot and return a signed link that stays valid for 7 days.
Node.js
const response = await fetch("https://api.fastscreenshotapi.com/v1/screenshot", {
method: "POST",
headers: {
"X-Api-Key": process.env.FASTSCREENSHOT_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://example.com", format: "webp" }),
});
const result = await response.json();
console.log(result.url, "expires at", result.expires_at);Python
response = requests.post(
"https://api.fastscreenshotapi.com/v1/screenshot",
headers={"X-Api-Key": os.environ["FASTSCREENSHOT_API_KEY"]},
json={"url": "https://example.com", "format": "webp"},
timeout=90,
)
response.raise_for_status()
result = response.json()
print(result["url"], "expires at", result["expires_at"])The object is deleted after 7 days. If you need it longer, download it and keep your own copy, or upload straight to your own bucket (see the async section).
3. Full pages, mobile views and PDFs
The same endpoint covers the common variations through a few parameters:
| Parameter | What it does |
|---|---|
full_page: true | Captures the whole scrollable page, not just the first screen |
mobile: true | Uses a mobile viewport and user agent |
format: "pdf" | Returns a PDF instead of an image (png, jpeg, webp, pdf) |
quality | Compression for JPEG and WebP, 1 to 100 |
block_cookie_banners | Dismisses cookie consent banners, on by default |
block_ads | Blocks ad scripts before capture |
scroll_to_bottom | Scrolls first so lazy-loaded images render, on by default |
delay | Extra wait after load in milliseconds, up to 10,000 |
A full-page mobile capture in Python:
response = requests.post(
"https://api.fastscreenshotapi.com/v1/screenshot",
headers={"X-Api-Key": os.environ["FASTSCREENSHOT_API_KEY"]},
json={
"url": "https://example.com",
"format": "jpeg",
"quality": 80,
"full_page": True,
"mobile": True,
"block_ads": True,
"response_type": "binary",
},
timeout=90,
)
response.raise_for_status()
open("example-mobile.jpg", "wb").write(response.content)And a PDF in Node.js:
const response = await fetch("https://api.fastscreenshotapi.com/v1/screenshot", {
method: "POST",
headers: {
"X-Api-Key": process.env.FASTSCREENSHOT_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/invoice/123",
format: "pdf",
full_page: true,
response_type: "binary",
}),
});
await writeFile("invoice.pdf", Buffer.from(await response.arrayBuffer()));Cookie banners are dismissed by default, so you rarely need to think about GDPR popups. Set block_cookie_banners to false only if you actually want the banner in the shot.
4. Render your own HTML
On paid plans you can send HTML instead of a URL. This is handy for OG images, invoices and email previews. html and url are mutually exclusive, the body can be up to 1 MB, and it only works with POST.
const html = `
<html>
<body style="font-family: sans-serif; padding: 48px">
<h1>Invoice #123</h1>
<p>Total: $500</p>
</body>
</html>`;
const response = await fetch("https://api.fastscreenshotapi.com/v1/screenshot", {
method: "POST",
headers: {
"X-Api-Key": process.env.FASTSCREENSHOT_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ html, format: "png", response_type: "binary" }),
});If any part of that HTML comes from your users, escape it before you build the string, the same way you would for a web page.
5. Async jobs with signed webhooks
Heavy pages, serverless functions with short timeouts and background pipelines are better served by the async endpoint. You submit a job, get a job_id immediately, and receive the result on your webhook.
response = requests.post(
"https://api.fastscreenshotapi.com/v1/screenshot/async",
headers={"X-Api-Key": os.environ["FASTSCREENSHOT_API_KEY"]},
json={
"url": "https://example.com",
"format": "png",
"full_page": True,
"webhook_url": "https://your-app.com/webhooks/screenshots",
"webhook_secret": os.environ["FASTSCREENSHOT_WEBHOOK_SECRET"],
},
timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["job_id"], job["status"]) # e.g. job_cZ1DADXGyzNM queuedWhen the job finishes, we POST a JSON payload with job_id, status, format and, on success, a signed screenshot_url. The body is signed with HMAC-SHA256 using your webhook_secret, and the hex digest arrives in the X-Webhook-Signature header.
Verify the signature over the raw request body, before you parse it, and compare in constant time.
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post(
"/webhooks/screenshots",
express.raw({ type: "application/json" }),
(req, res) => {
const expected = crypto
.createHmac("sha256", process.env.FASTSCREENSHOT_WEBHOOK_SECRET)
.update(req.body) // raw Buffer, not re-serialized JSON
.digest("hex");
const received = req.get("X-Webhook-Signature") ?? "";
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.status(401).send("Invalid signature");
const event = JSON.parse(req.body.toString("utf8"));
if (event.status === "completed") {
console.log(`Job ${event.job_id} ready: ${event.screenshot_url}`);
} else {
console.log(`Job ${event.job_id} failed: ${event.error_code}`);
}
res.sendStatus(200);
},
);
app.listen(3000);Python (Flask)
import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["FASTSCREENSHOT_WEBHOOK_SECRET"].encode()
@app.post("/webhooks/screenshots")
def screenshot_webhook():
expected = hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
received = request.headers.get("X-Webhook-Signature", "")
if not hmac.compare_digest(received, expected):
abort(401)
event = request.get_json()
if event["status"] == "completed":
print(f"Job {event['job_id']} ready: {event['screenshot_url']}")
else:
print(f"Job {event['job_id']} failed: {event['error_code']}")
return "", 200No public endpoint yet? Poll instead with GET /v1/screenshot/status/{job_id}. Status checks don't use quota:
const res = await fetch(
`https://api.fastscreenshotapi.com/v1/screenshot/status/${jobId}`,
{ headers: { "X-Api-Key": process.env.FASTSCREENSHOT_API_KEY } },
);
const job = await res.json(); // { job_id, status: "queued" | "processing" | "completed" | "failed", ... }Async jobs can also deliver straight to your own S3, R2 or other S3-compatible bucket with an upload_to block; see the external storage docs.
6. Many URLs in one call
The batch endpoint turns a list of URLs into async jobs that share the same options. The maximum batch size depends on your plan, from 100 URLs on Starter to 5,000 on Enterprise.
response = requests.post(
"https://api.fastscreenshotapi.com/v1/screenshot/batch",
headers={"X-Api-Key": os.environ["FASTSCREENSHOT_API_KEY"]},
json={
"urls": [
"https://example.com",
"https://example.org",
"https://example.net",
],
"format": "webp",
"full_page": True,
"webhook_url": "https://your-app.com/webhooks/screenshots",
"webhook_secret": os.environ["FASTSCREENSHOT_WEBHOOK_SECRET"],
},
timeout=30,
)
response.raise_for_status()
batch = response.json()
for job in batch["jobs"]:
print(job["job_id"], job["url"])Each job then reports to the same webhook, so the handler above works unchanged. If a batch is larger than what is left of your monthly quota, only the URLs that fit are queued and the response says how many were skipped.
Handling errors
Errors return a JSON body with a stable code. The ones worth handling explicitly:
INVALID_URLorINVALID_PARAMS(400): fix the request, don't retry.FEATURE_RESTRICTED(403): the option needs a higher plan.QUOTA_EXCEEDEDorRATE_LIMITED(429): back off;X-RateLimit-Resettells you when.SCREENSHOT_TIMEOUT(504),SCREENSHOT_FAILED(502),SERVICE_OVERLOADED(503): retry with exponential backoff.
The full list is in the error code reference.
Wrapping up
For most apps, the synchronous endpoint with response_type: "url" is all you need. Move to async jobs and webhooks when pages get heavy or volumes grow, and to batches when you capture lists of URLs. Get a free API key and try the snippets above against your own pages, or see pricing for higher volumes.