How to Use Thumbalizr with WordPress for Automatic Page Thumbnails
Build a custom WordPress shortcode that embeds Thumbalizr screenshots, signs requests safely, and caches results to avoid repeated captures.
Short answer: Thumbalizr’s documented option for displaying screenshots on a website is its Embed API. The official materials reviewed do not document a dedicated WordPress plugin or automatic post integration. You can build a custom shortcode that signs the Embed API request on your server, displays the resulting image, and lets WordPress determine which URL to capture and when to refresh it. Treat this as a custom integration pattern, not an official or tested WordPress workflow.
Thumbalizr’s [Embed API documentation](https://www.thumbalizr.com/api/embed/) describes embedding and provides PHP URL-generation guidance. Keep the secret used to sign requests on the server. The API key and secret are available through the Thumbalizr member area; its homepage describes basic API key signup as free and requiring no credit card. Check the current account terms and feature availability before relying on a specific option.
1. Decide what “automatic” means for your site
WordPress does not learn which page you want screenshotted from Thumbalizr. Your integration must define that mapping and its refresh rules. Common choices include:
- Capture the current post’s canonical permalink.
- Store a different target URL in a post meta field for external pages.
- Let an editor supply a URL through a custom field, then render a shortcode for that post.
Also choose whether WordPress embeds the generated Thumbalizr URL directly or downloads a screenshot and stores it locally. Direct embedding avoids managing local files, while downloading gives you control over local storage and display caching. The official PHP library overview describes URL generation and downloading or waiting for a thumbnail; the sources do not provide a WordPress-specific comparison or benchmark.
2. Get the Embed API credentials
- Create or sign in to a Thumbalizr account.
- Find the Embed API key and secret in the member area.
- Store them in server configuration or environment-backed constants. Do not put the secret in browser JavaScript, a shortcode attribute, or rendered page HTML.
The Embed API token is derived from the query string and secret. Correct URL encoding matters: build the query from parameter values using a URL encoder, then sign it in the way the official API example specifies. Do not hand-concatenate a target URL containing characters such as &, ?, spaces, or non-ASCII text.
3. Add a minimal server-side shortcode
The following illustrates the shape of a custom shortcode. It assumes you have checked the current Embed API documentation and verified its signing and parameter requirements for your account. Replace the placeholder signing step with the exact token construction shown in the official PHP example before deployment; this article does not claim this sample is vendor-tested.
<?php
// Put credentials in server configuration, not in a public shortcode.
// Example wp-config.php constants:
// define('THUMBALIZR_KEY', 'your-account-key');
// define('THUMBALIZR_SECRET', 'your-account-secret');
function site_thumbalizr_shortcode($atts) {
if (!defined('THUMBALIZR_KEY') || !defined('THUMBALIZR_SECRET')) {
return '';
}
$atts = shortcode_atts(array(
'url' => get_permalink(),
'width' => '400',
'format' => 'png',
'alt' => 'Page thumbnail',
), $atts, 'thumbalizr');
$target = esc_url_raw($atts['url']);
$parts = wp_parse_url($target);
if (!$parts || empty($parts['scheme']) || !in_array($parts['scheme'], array('http', 'https'), true)) {
return '';
}
$params = array(
'key' => THUMBALIZR_KEY,
'url' => $target,
'width' => absint($atts['width']),
'format' => sanitize_key($atts['format']),
);
// Construct the exact canonical query and token required by the current
// Thumbalizr Embed API docs. Do not guess the signing algorithm here.
$query = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
$token = site_thumbalizr_token_from_official_example($query, THUMBALIZR_SECRET);
if (!$token) {
return '';
}
$src = 'https://api.thumbalizr.com/?' . $query . '&token=' . rawurlencode($token);
return sprintf('<img loading="lazy" src="%s" alt="%s">', esc_url($src), esc_attr($atts['alt']));
}
add_shortcode('thumbalizr', 'site_thumbalizr_shortcode');
site_thumbalizr_token_from_official_example() is intentionally a placeholder: implement it from Thumbalizr’s current official PHP example and use the exact endpoint and parameter names documented for your account. The research materials establish that the Embed API URL includes an account key and a token made from the query string and secret, but do not reproduce enough exact signing detail here to safely invent a runnable token algorithm.
Use the shortcode in a post, for example [thumbalizr] to capture its permalink or [thumbalizr url="https://example.com/page"] for an explicit target. Sanitize the URL and constrain shortcode attributes to settings you intend to allow. If editors should set a target independently of post content, a post meta field is generally clearer than repeating a long URL in the shortcode.
4. Add caching and a refresh policy
Do not build a shortcode that creates a new capture on every visitor request. Decide when captures are requested and where the result is reused. For example, store the generated URL or downloaded image reference in post metadata, then refresh it when the target URL changes or after a chosen interval. This is implementation guidance based on the API’s generation and status model; it is not a documented Thumbalizr WordPress feature.
- Cache key: include the normalized target URL and every capture option that changes output.
- Refresh: set a deliberate interval or trigger refresh when an editor updates the target.
- Concurrency: prevent multiple simultaneous refresh requests for the same post, for example with a short-lived lock.
- Failure behavior: retain the last known good image or render a local placeholder while a new capture is queued or failed.
- Privacy: remember that a locally downloaded screenshot consumes your storage and delivery bandwidth; an embedded image keeps the file hosted by the screenshot service.
5. Choose capture options deliberately
Thumbalizr’s documentation describes options including width, output format, JPEG quality, capture size, delay, browser dimensions, and country. Availability can depend on membership level. Confirm current limits and syntax in the [API documentation](https://www.thumbalizr.com/api/embed/) and demo before exposing settings to editors.
| Option | When to use it | Things to check |
|---|---|---|
width |
Set the output image width to fit your card or content layout. | Verify supported range and whether output is scaled or captured at that width. |
format |
Choose a format your theme and target browsers support. | Confirm accepted values for your account. |
quality |
Adjust JPEG size and visual quality. | Relevant to JPEG output; confirm allowed values. |
size |
Choose screen-sized or page-sized capture where available. | Free access is described as screen-size only; full-page capture may be tier-limited. |
bwidth, bheight |
Set the browser viewport for the page being captured. | The free demo describes a fixed 1280×1024 browser size. |
| delay | Allow a page time to render before capture. | Custom delay may be tier-limited; larger delays add capture latency. |
| country | Request a geographically specific page variant if supported. | Confirm supported locations and membership restrictions. |
The free demo describes watermarking, screen-size rather than full-page captures, and a fixed 1280×1024 browser size. The API tier table lists additional options at paid membership levels. Do not promise a feature based on an old example; check your live account terms.
6. Handle asynchronous status and errors
Thumbalizr documents X-Thumbalizr-Status values QUEUED, OK, and FAILED, alongside generated-time and error headers. Your integration should not assume every image is ready immediately. If you download results server-side, inspect the response headers, apply a bounded retry strategy for queued work, and log failure details without exposing credentials. If embedding directly, provide a placeholder or retain a previous image until a fresh capture succeeds.
- Queued: defer refresh and retry after a short interval rather than polling on every page view.
- Failed: keep the previous successful image if available; log the status and error header for administrators.
- Empty or broken image: verify the URL, token generation, encoding, account options, and returned content type.
7. Security, performance, and cost
Security
- Keep the API secret server-side and restrict who can change credentials.
- Validate schemes and sanitize target URLs. If a public form can supply targets, restrict destinations to avoid turning your site into an arbitrary URL-fetching proxy.
- Escape the final image URL and alt text before rendering HTML.
- Avoid logging full signed URLs if they contain credentials or tokens.
Performance and reliability
Captures can be queued, so generating them in the front-end request path can make pages slower or produce inconsistent results. Cache the last successful output, refresh outside normal page rendering where your WordPress setup allows it, and use a timeout and finite retry count for server-side downloads. This is general implementation guidance, not a measured Thumbalizr performance claim.
Cost and plan fit
The reviewed sources do not establish current prices or quotas. The free demo’s watermark and capture limits may be unsuitable for production cards. Check the current account tier for the options you need, especially full-page capture, custom viewport, delay, and geography. Avoid promising a capture feature to editors until the account has been confirmed to support it.
8. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Image request is rejected or blank | Wrong key, token, endpoint, or query-string signing order. | Rebuild the request exactly as the current official PHP example specifies; ensure values are URL-encoded before signing. |
| Target URL breaks after adding query parameters | The target URL was concatenated without proper encoding. | Use a standards-compliant query builder such as PHP http_build_query() and follow the API’s signing rules. |
| Capture stays pending | The job is queued or the page needs more time. | Inspect X-Thumbalizr-Status; retry later with a bounded schedule and avoid request-per-view polling. |
| Capture reports failure | The remote page could not be captured or an option is invalid or unavailable. | Inspect the error header, retry only transient failures, and verify that the selected options are enabled for the account. |
| Thumbnail is watermarked or not full-page | Those are described free-tier limitations. | Check current plan features before relying on watermark-free or full-page output. |
| Every post view triggers another capture | The result was not persisted or the cache key changes unexpectedly. | Store successful results and normalize the URL and options used in the cache key. |
| Shortcode displays no image | Credentials are missing, URL validation failed, or the token helper is not implemented. | Check server configuration and logs, then test a known valid URL using the official API example. |
9. Or skip the browser setup
If your goal is simply to get screenshots into a WordPress workflow, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. See the API documentation for its options and integration details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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, newsletter popups, and chat widgets before the screenshot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; response headers identify the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo free: 1,000 screenshots a month, no card required.
FAQ
Is there an official Thumbalizr WordPress plugin?
The reviewed official materials do not document one. The shortcode pattern above is a custom integration approach.
Can WordPress capture each post automatically?
Yes, if your custom code maps a post to a target URL and defines when to generate and refresh the screenshot. Thumbalizr’s API does not define that WordPress behavior for you.
Can the API secret be placed in a shortcode?
No. Keep it in server-side configuration and generate the signed request on the server.
Does free access include full-page, unwatermarked thumbnails?
The reviewed demo describes watermarked, screen-size captures and a fixed viewport for free membership. Verify current account terms because plan features can change.
What happens during Thumbalizr’s backend migration?
Thumbalizr’s April 8, 2026 vendor announcement says newly created accounts use ScreenshotCenter and says existing API calls, embed codes, settings, and integrations are intended to remain unchanged. Check the vendor’s current migration notice for rollout status.
