How to Use URL2PNG to Create Social Media Preview Images

URL2PNG can capture a webpage and return an image you can host as a social preview image. You still need to add the appropriate social metadata to the page you share and check that the target platform can fetch and display the image: a screenshot alone does not create or guarantee a social preview.

This guide covers the URL2PNG v6 request, capture settings, publishing workflow, and common problems. API details and defaults below are from the URL2PNG Quickstart Guide; check the live docs before deploying because API behavior can change. The examples illustrate request construction and have not been run here.

1. Decide what the social image should show

Choose the page URL and composition before building the request. A viewport capture shows a selected screen-sized region; a full-page capture can include the entire document and may be too tall for a card. For a card-like crop, choose a viewport deliberately and inspect the returned image at the intended display size. The URL2PNG materials do not establish one universally correct aspect ratio for social networks.

• Viewport-only: use when the important content fits in a deliberate crop.
• Full page: use when readers should see the whole page, and check how the resulting tall image is rendered by the destination.
• Scaled output: use thumbnail_max_width to constrain the output width after choosing the capture viewport.

For a dynamic page, decide what event means the useful content is ready. URL2PNG documents a delay and a say_cheese element wait. Avoid choosing a delay by guesswork if the page provides a reliable element that signals readiness.

2. Build and sign a URL2PNG v6 request

The documented request includes an API key, a security token, and the target URL. The token is an MD5 hash derived from the complete query string and your secret key. Follow the current official documentation for the exact parameter ordering, encoding, and signature construction; do not expose the secret key in browser-side code or a public page.

The quickstart contains language examples for signing requests. Because URL encoding and parameter order affect the signature, use its current example for your language rather than copying an old snippet or assembling the signature differently. Keep the API secret in server-side configuration or a secret manager, and send the request from a backend job or service.

3. Tune the capture options

Setting	What it controls	When to use it
viewport	Browser viewport dimensions. The documented default is 1480x1037.	Set explicit dimensions to frame a card-like crop or match a known page layout.
fullpage	Whether to capture the full document; the documented default is false.	Enable only when the complete page is intended for the image.
thumbnail_max_width	Maximum output width used to scale the image.	Limit output width after choosing the viewport.
delay	Waits after document readiness and asset loading.	Allow time for content that appears shortly after the initial render.
say_cheese	Waits for a specified page element.	Prefer a concrete readiness marker when the content is asynchronous.
custom_css_url	Applies custom CSS to the captured page.	Hide irrelevant elements or adjust capture styling using a CSS resource you control.
unique	Varies the request to ask for a fresh screenshot.	Use when the page has changed and you need a new render rather than a cached image.
TTL	Controls cache freshness. The documented default is 2,592,000 seconds (30 days).	Choose a shorter or longer cache lifetime based on how often the source page changes.
Language and user agent	Changes request language or browser identity.	Use when the page renders different content based on either value.

Keep the capture settings consistent for a given social image so repeated builds have predictable framing. If content changes, use the documented freshness controls and account for URL2PNG’s render-based plan usage.

4. Store the result and publish the social preview

1. Make the signed request from a backend process using the target page URL and selected capture options.
2. Save the returned image to storage or a web server that can serve it at a stable, publicly reachable URL suitable for the page and platform.
3. Add the social metadata required by the destination platform to the page being shared, including a reference to the hosted image where required.
4. Use the destination platform’s current preview validation tool to check the shared page URL. Confirm that the platform can fetch both the page and image, and inspect the actual crop.
5. When the page or image changes, refresh the generated file and consider URL2PNG’s cache freshness settings as well as any cache in your own storage or delivery layer.

URL2PNG’s reviewed documentation describes screenshot capture; it does not describe inserting social metadata into your page or guaranteeing how a platform will render a preview. Treat capture and social publishing as separate steps.

5. Troubleshooting

Symptom	Likely cause	What to check
Authentication or signature error	The key is wrong, the token was built from a different query string, or encoding/parameter order differs.	Rebuild the request using the current official signing example. Sign the exact complete query string and keep the secret server-side.
The image shows an old page	A cached render is being reused.	Review TTL and use the documented unique value when a fresh render is required.
Important content is missing	The capture happened before asynchronous content appeared, or the viewport crop excludes it.	Set the viewport intentionally and use say_cheese or an appropriate delay.
The resulting image is too tall	fullpage captured the complete document.	Use viewport-only capture for a compact card, or retain full-page output only if that format is intended.
The platform shows no preview	A screenshot was generated, but the shared page lacks suitable metadata, the image is not publicly fetchable, or the platform has not refreshed its cached preview.	Check the page metadata, public image access, and the platform’s current preview debugger. URL2PNG capture alone does not publish metadata.
Image composition differs by request	Viewport, language, user agent, page state, or content timing differs.	Hold those settings constant and use a page readiness signal for dynamic content.

6. Performance, reliability, and cost

Capture time depends on the target page and when its content becomes ready; the reviewed sources provide no benchmark to use as a general guarantee. A readiness element can avoid waiting an arbitrary long time, while an unnecessarily long delay adds time to each request. If generating images for many pages, use a backend queue and handle failures so a temporary capture problem does not block publishing.

URL2PNG says newly generated screenshots count as renders and cached loads do not count against plan usage. Its plans and quotas can change, so check the current URL2PNG plans before estimating recurring cost. Set TTL according to how frequently source pages change, and request fresh output only when needed.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. For a social image, a direct image response can be saved or served from your application. See the ScreenshotNeo API documentation for authentication and available options.

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}`);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up free and capture your first screenshots.

FAQ

Does URL2PNG create the social card metadata?

The reviewed URL2PNG materials describe capturing an image, not adding metadata to your page. Add the destination platform’s required metadata separately.

Should I use a full-page screenshot for a social preview?

Only if the whole document is useful in the destination’s preview. A viewport capture gives you more control over a compact composition.

Can I sign a URL2PNG request in frontend JavaScript?

Keep the secret key out of browser code. Construct and sign the request on a server you control.

How often should I refresh the generated image?

Refresh it when the source content or desired composition changes, and choose cache freshness settings that fit that publishing schedule.