Cloudinary website screenshot API: how to capture a URL as an image

To capture a URL as an image with Cloudinary, use its URL2PNG Website Screenshots add-on. Set the delivery type to url2png and use the public webpage URL as the screenshot request’s public ID. Cloudinary renders and caches the screenshot, which you can then resize, crop, or deliver through its image pipeline. Cloudinary’s fetch feature is different: it retrieves a remote image or video; it does not render webpage HTML into a screenshot.

This guide covers the required setup, request authorization, capture options, transformations, persistence, costs, and common failures. The examples use a public target page; they do not imply that private or access-restricted pages can be captured.

1. Set up URL2PNG Website Screenshots

Create or use a Cloudinary account.
Register for the URL2PNG Website Screenshots add-on.
Use your own Cloudinary cloud name and account configuration in examples. A demo cloud name is illustrative only and is not a substitute for registering the add-on.
Choose whether to sign screenshot delivery URLs or generate screenshots eagerly with the authenticated API. Signing or eager generation is the documented default.

Keep the API secret on a server. Do not put it in browser code. Cloudinary requires authorization for dynamic URL2PNG transformations by default because an unplanned screenshot URL can incur add-on usage. Security settings can change the unsigned-transformation requirement; assess that choice against your own exposure and cost controls.

2. Build a screenshot URL

The URL2PNG delivery type is url2png; the target site URL is the public ID. Cloudinary’s SDK URL builders can construct the delivery URL, and the result must be signed under the default security behavior.

import { v2 as cloudinary } from 'cloudinary';

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true
});

const target = 'https://stripe.com';
const screenshotUrl = cloudinary.url(target, {
  type: 'url2png',
  sign_url: true,
  secure: true
});

console.log(screenshotUrl);

Install the Cloudinary JavaScript SDK in your server-side project and set the three environment variables from your account. The generated URL can be delivered to a client after signing; do not ship the secret. SDK versions and helper signatures can vary, so check the current SDK documentation for your installed version if the helper rejects an option.

The URL form is conceptually https://res.cloudinary.com/<cloud>/image/url2png/<options>/<encoded-target-url>, with the required signature included for a signed dynamic transformation. Use an SDK builder or the authenticated API instead of hand-assembling signatures and URL encoding.

3. Choose signed delivery or eager generation

Signed dynamic URL

Generate a signed URL server-side when a user requests a preview. The screenshot is generated on demand and Cloudinary caches it for delivery. This fits previews whose target URLs are not known in advance, while authorization prevents arbitrary visitors from constructing billable screenshot requests.

Eager generation

For known pages or a repeatable gallery, use the authenticated explicit API flow to eagerly generate the screenshot, then deliver the generated asset. This separates the capture operation from later page views. Keep the API call authenticated on the server and retain the returned asset information needed by your application.

Cloudinary’s January 2026 Next.js tutorial demonstrates saving generated previews as permanent assets so gallery views do not repeatedly trigger capture. Treat this as an implementation pattern, not a requirement: whether to persist depends on how often targets change and how your application manages assets.

4. Configure the capture and the delivered image

URL2PNG capture controls and Cloudinary image transformations solve different problems. Capture controls influence how the webpage is rendered; image transformations operate on the resulting screenshot.

Need	Relevant setting or step	Notes
Set the browser viewport	`viewport`	Choose dimensions that suit the intended layout, such as a mobile or desktop preview.
Use a particular browser identity	`user_agent`	Some sites vary layout by user agent. A different user agent does not bypass access controls.
Allow a page to settle	`delay`	A delay can help with content that appears after initial load, but adds capture time and cannot guarantee every dynamic interaction completes.
Capture only the initial viewport	`fullpage=false`	Use when the preview should show the visible viewport instead of the full document.
Resize or crop the resulting image	Cloudinary image transformations	Apply after screenshot generation; this does not change the webpage capture viewport.

Option names and the URL pattern are documented by Cloudinary as <Website URL>/url2png/<option1=value1>|<option2=value2>|.... These examples are not the complete option list. Consult the URL2PNG documentation for supported values and current syntax. Once a screenshot exists, Cloudinary’s regular image pipeline can apply transformations to that image.

5. Decide whether previews should be generated on demand or saved

On-demand: request a signed URL when a preview is needed. This keeps the integration simple for changing or user-submitted URLs, but repeated misses or distinct targets may trigger screenshot work.
Eager and saved: capture known targets with the authenticated API and store the resulting asset reference. This is useful for galleries with repeated views and gives the application a durable asset to deliver.
Refresh deliberately: decide when a page change should produce a new preview. Avoid generating a new capture on every gallery render if the existing image is acceptable.

Cloudinary’s add-on says screenshots are generated and cached. Caching helps repeated delivery of the same generated result, but application behavior, target changes, and URL differences affect whether a request reuses the same result. Do not assume a particular cache lifetime or browser fidelity beyond the documented behavior.

6. Estimate quota and cost

The Cloudinary add-ons marketplace listed these URL2PNG quotas and prices when the research for this article was retrieved on October 3, 2026. Pricing is vendor information and can change; verify availability, current pricing, and base-account requirements in your account console before planning a purchase.

Marketplace tier	Monthly screenshots	Listed price
Free	50	Free
Bronze	1,000	$6/month
Silver	5,000	$30/month
Gold	15,000	$75/month
Titanium	50,000	$200/month

Cloudinary’s add-on guidance says higher-quota paid tiers generally require a paid Cloudinary account and mid-cycle upgrades are prorated. Estimate captures from unique or refreshed targets, not just page views: delivering a previously generated asset and triggering a new screenshot are different operations.

7. Troubleshoot common problems

Symptom	Likely cause	What to check
Transformation is rejected or unavailable	The account is not registered for URL2PNG, or the dynamic request is unsigned while signing is required.	Confirm add-on registration. Generate a signed URL with the SDK or eagerly generate through the authenticated API.
Screenshot request works in one context but not another	The signature may not match the exact URL and transformation components.	Build and sign the final URL server-side after setting the target and options. Avoid editing signed URL components afterward.
The result is an error or an unexpected media response	The request may use `fetch` rather than the `url2png` delivery type.	Use URL2PNG to render a webpage. Use `fetch` for an existing remote image or video.
The requested page does not appear as expected	The page may require authentication, interaction, or special loading behavior, or may block automated access.	Test with an accessible public page, confirm the target URL, and consult URL2PNG’s supported capture options. The sources do not promise capture of private pages, bot challenges, or pages requiring special interaction.
Mobile or desktop layout is wrong	The capture viewport or user agent does not match the page layout you expect.	Set an appropriate `viewport` and, if needed, `user_agent`; distinguish capture dimensions from later crop/resize transformations.
Important content is missing	Content may load after the capture begins.	Try a documented `delay` value and check whether the page needs interaction that URL2PNG does not provide.
Target URL breaks the delivery URL	Nested URL characters may not be encoded correctly.	Pass the complete target to the SDK URL builder; do not concatenate an unescaped URL into a signed transformation path.

8. Performance and reliability considerations

Screenshot generation requires rendering a webpage, so it is more work than delivering an existing image. Avoid tying every repeated gallery view to a fresh capture.
Use a viewport appropriate to the card or preview; full-page output can be larger than a viewport-sized thumbnail.
Use delays only when the page needs time for content to appear. Longer waits increase the time before the image is ready.
For predictable previews, eagerly generate and save assets, and define an application-level refresh policy.
Plan for target pages that change, fail to load, require sign-in, or restrict automated access. The cited documentation does not establish capture guarantees for those cases.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns an image or PDF, and its parameters used by other screenshot APIs also work.

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,
)
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: ${res.status}`);
await Bun.write('shot.webp', res);

See the ScreenshotNeo API documentation for options and request details. Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, and failed loads are never billed; response headers identify the page verdict and billing status. Its MCP server lets AI agents use screenshot, page information, and PDF capture tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Can Cloudinary URL2PNG capture any URL?

The documented add-on is for public webpages. The available sources do not promise capture of authenticated pages, bot challenges, or pages that need special interaction.

Is URL2PNG the same as Cloudinary fetch?

No. URL2PNG renders webpage HTML as a screenshot. Fetch retrieves remote media such as an existing image or video.

Can I resize the screenshot after capture?

Yes. URL2PNG-specific settings control webpage capture; Cloudinary image transformations can resize or crop the resulting screenshot for delivery.

Do I need to sign every delivery URL?

By default, dynamic URL2PNG transformations must be signed or eagerly generated through the authenticated API. Cloudinary allows changing this requirement in security settings.