Cloudinary Website Screenshot API Tutorial in Node.js
Generate website screenshots in Node.js with Cloudinary URL2PNG. Learn URL signing, capture options, image transformations, permanent storage, and troubleshooting.
To generate a website screenshot in Node.js with Cloudinary, enable the URL2PNG Website Screenshots add-on, then ask the Cloudinary Node.js SDK to build a delivery URL with type: "url2png". The add-on captures the public website; the SDK constructs a Cloudinary URL and can sign it. This is not a generic screenshot endpoint provided by the Node.js SDK alone. See the URL2PNG add-on documentation and the Node.js integration guide.
1. Enable URL2PNG and configure Node.js
- Create or use a Cloudinary account and register for the URL2PNG Website Screenshots add-on.
- Configure the SDK on a server with your Cloudinary credentials. The SDK can read
CLOUDINARY_URLor use explicit configuration. - Keep the API secret on the server. Do not put it in browser code, commit it to a public repository, or expose an unprotected environment file.
Install the SDK:
npm install cloudinaryFor example, place the account URL in a server-side environment variable:
# .env (keep this file out of version control)
CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAMELoad the value through your deployment’s secret manager or a local environment loader. The following examples assume the variable has already been set.
2. Generate a signed screenshot URL
Run this server-side Node.js script to print a signed URL for a public page:
// screenshot-url.js
const cloudinary = require("cloudinary").v2;
const screenshotUrl = cloudinary.url("https://example.com", {
type: "url2png",
sign_url: true
});
console.log(screenshotUrl);Run it with node screenshot-url.js. The result is a Cloudinary delivery URL that represents the screenshot request. It can be returned by a server endpoint or used in an image element, subject to your application’s access controls and Cloudinary URL settings.
By default, delivery URLs using this add-on must be signed or eagerly generated. Cloudinary also provides an account Security setting to permit unsigned add-on transformations. Signed URLs are the safer default when you do not want arbitrary clients creating transformations under your account. Never move signing credentials to the browser. See Cloudinary’s add-on security details.
3. Set capture inputs separately from image output
URL2PNG capture inputs control what the remote browser captures. Documented inputs include viewport, user agent, delay, and full-page behavior. The exact option syntax belongs to the add-on’s URL2PNG resource path; check the current add-on reference before adding those path options. Do not assume a browser viewport is the same as the final delivered image size.
| Need | Set | What it affects |
|---|---|---|
| Desktop or mobile rendering | Capture viewport and, when needed, user agent | The page layout and content rendered by the remote browser |
| Allow client-side content to appear | Capture delay | How long capture waits before taking the screenshot |
| Capture beyond the initial viewport | Full-page behavior | The vertical extent captured from the public page |
| Fit a card or preview | Cloudinary image transformation | The resulting image’s crop or dimensions after capture |
Cloudinary’s Node.js SDK can apply ordinary image transformations to the generated resource URL. For example, keep the capture request and output transformation conceptually distinct: first specify URL2PNG capture behavior in the resource path as documented by the add-on, then use Cloudinary’s documented transformation options for a preview size or crop. The minimal SDK example above deliberately avoids guessing add-on path syntax that may change.
4. Dynamic delivery or a permanent asset?
A generated URL can deliver a screenshot dynamically. Having that URL does not mean the screenshot has been saved as a permanent managed asset. If your application needs a durable Media Library resource, generate the screenshot through the supported authenticated workflow and upload the resulting image to Cloudinary as a separate step. The official Cloudinary tutorial demonstrates uploading the result to the Media Library.
| Approach | Useful when | Trade-off |
|---|---|---|
| Signed dynamic URL | The screenshot should be generated or delivered on demand | Capture and delivery remain tied to the URL request and its settings |
| Eager generation | You want to generate through an authenticated workflow ahead of delivery | Requires a generation step before the asset is requested |
| Upload to Media Library | The result must be retained as a managed asset | Persistence is an additional authenticated upload step |
5. Public pages, access, and security boundaries
The add-on is for capturing public websites. Do not expect it to use a visitor’s logged-in browser session or access private pages that require that user’s cookies. Treat the target URL as an input that your application validates: restrict it to expected public hosts when callers can supply URLs, and avoid building an open screenshot proxy. Keep Cloudinary signing and upload credentials exclusively on the server.
6. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Add-on or transformation error | URL2PNG is not enabled for the Cloudinary account | Register for the URL2PNG Website Screenshots add-on and retry. |
| Unsigned URL is rejected | The account enforces the default signed-or-eager requirement | Generate a signed URL server-side or use the documented eager workflow. Only change the account security setting if unsigned transformations are intended. |
| Signature is invalid | The URL was changed after signing, credentials do not match the account, or signing was performed with the wrong configuration | Regenerate the URL on the server with the correct Cloudinary credentials; do not edit a signed URL’s path or transformation afterward. |
| Target page cannot be captured as expected | The site is not publicly accessible, blocks remote access, or has not rendered its content by capture time | Confirm the page is public and reachable, then tune documented viewport, user agent, or delay options. This add-on is not a logged-in browser session. |
| Screenshot is too small or cropped | Capture viewport and output transformation were treated as the same setting | Adjust the documented capture viewport or full-page option, then separately change the output crop or resize transformation. |
| Screenshot URL works but no durable asset appears | Dynamic delivery was mistaken for Media Library persistence | Use the authenticated workflow to upload the generated result as a separate step. |
| Credentials work locally but fail in deployment | CLOUDINARY_URL is absent, malformed, or belongs to another account |
Set the correct secret in the deployment environment and verify the cloud name and credentials without printing the secret. |
7. Performance, reliability, and cost considerations
- Capture time: Delay can help pages that render content asynchronously, but adds waiting to each capture. Use only the delay needed for the page’s content.
- Output size: Full-page captures can produce taller images than viewport captures. Apply a suitable output resize or crop for downstream previews.
- Repeat requests: Reuse a generated URL or a persisted asset where your application needs the same result; avoid triggering fresh captures unnecessarily.
- Failure handling: Treat remote page capture as dependent on both Cloudinary’s add-on and the target site’s availability and rendering behavior. Handle delivery failures in the application and provide a retry path appropriate to your workload.
- Cost: The research sources provide no current URL2PNG add-on price, capture benchmark, or usage limit. Check your Cloudinary account’s current add-on and plan terms before estimating production cost.
8. FAQ
Can I call a generic screenshot method in the Node.js SDK?
No. For this workflow, the SDK constructs a Cloudinary URL using the URL2PNG delivery type; screenshot capture comes from the enabled add-on.
Can URL2PNG capture a private dashboard using my app’s browser login?
The documented target is a public website. The supplied research does not establish a workflow for borrowing a user’s authenticated browser session.
Does a signed delivery URL save the screenshot permanently?
No. A delivery URL and a stored Media Library asset are different outcomes. Upload the result through an authenticated step when persistence is required.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. It accepts one GET request for a URL and returns a PNG, JPEG, WebP, or PDF. Cookie banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, and failed loads are never billed, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. One thousand screenshots a month are free with no card; paid plans start at $5 for 3,000.
See the ScreenshotNeo API documentation. For a Node.js request:
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}`);
const image = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', image);Or make the same request with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpStart with ScreenshotNeo’s free account: 1,000 screenshots a month, no card required.
