How to Use the Thumbalizr API with a WordPress Website
Build a custom WordPress integration for Thumbalizr’s Embed API. Learn how to sign requests, keep credentials private, render thumbnails, and troubleshoot failures.
To show Thumbalizr screenshots on a WordPress site, make a server-side PHP integration with its Embed API. Generate the signed image URL on your server and render it in a shortcode, block, or theme component. Thumbalizr’s listed integrations do not show a WordPress-specific extension, so this guide describes a custom integration rather than a drop-in plugin.
The key security point is to keep the Embed API secret on the server. The browser can receive the signed image URL, but your secret should never be placed in post content, a public HTML attribute, or visitor-facing JavaScript.
How the WordPress integration works
- Sign up with Thumbalizr and retrieve the Embed API key and secret from the member area.
- Build a query string from the target page URL and any options.
- Compute the token as the MD5 of that encoded query string concatenated with your secret.
- Use the signed Embed API URL as the image source.
The documented endpoint format is https://api.thumbalizr.com/api/v1/embed/EMBED_API_KEY/TOKEN/?.... The API documentation says url is the only required option; other options can fall back to profile defaults. Follow the signing flow in the vendor documentation exactly, including its URL encoding rules. See the official PHP library and sample for the vendor’s PHP mechanics.
Configure the credentials on the server
Put the key and secret in server-controlled configuration. For example, define them in wp-config.php or load them from environment variables through your hosting setup. This example uses constants:
define('THUMBALIZR_EMBED_KEY', 'your_embed_key');
define('THUMBALIZR_EMBED_SECRET', 'your_embed_secret');Restrict access to configuration and avoid committing real credentials to a public repository. Do not copy the secret into a WordPress page or post editor. For production, confirm the configuration method against your hosting and deployment practices.
Build a signed Embed API URL in PHP
The following function shows the documented signing shape: URL-encode the query values, append the options, compute md5($query . $secret), and put that token in the endpoint path. It accepts only an HTTP or HTTPS target URL to avoid generating a request for a malformed value. Confirm encoding and option behavior against Thumbalizr’s current documentation before production use.
<?php
function mysite_thumbalizr_url($target_url, $options = array()) {
if (!filter_var($target_url, FILTER_VALIDATE_URL)) {
return new WP_Error('thumbalizr_invalid_url', 'Enter a valid target URL.');
}
$scheme = strtolower((string) parse_url($target_url, PHP_URL_SCHEME));
if (!in_array($scheme, array('http', 'https'), true)) {
return new WP_Error('thumbalizr_invalid_scheme', 'Only HTTP and HTTPS URLs are supported.');
}
if (!defined('THUMBALIZR_EMBED_KEY') || !defined('THUMBALIZR_EMBED_SECRET')) {
return new WP_Error('thumbalizr_missing_credentials', 'Thumbalizr credentials are not configured.');
}
$params = array_merge(array('url' => $target_url), $options);
$pairs = array();
foreach ($params as $name => $value) {
if (!is_scalar($value)) {
return new WP_Error('thumbalizr_invalid_option', 'Thumbalizr options must be scalar values.');
}
$pairs[] = urlencode((string) $name) . '=' . urlencode((string) $value);
}
$query = implode('&', $pairs);
$token = md5($query . THUMBALIZR_EMBED_SECRET);
return 'https://api.thumbalizr.com/api/v1/embed/' . rawurlencode(THUMBALIZR_EMBED_KEY) . '/' . $token . '/?' . $query;
}WordPress has its own escaping and URL-handling conventions, and the exact signing input must match the vendor’s documented format. Treat this as an integration example to adapt and verify against the current API documentation, not as a ready-made plugin.
Render a thumbnail with a shortcode
A shortcode is one way to let editors insert an image while keeping URL generation in PHP. This example takes a target URL and optional width; add only options supported by your account and the current API tier.
function mysite_thumbalizr_shortcode($atts) {
$atts = shortcode_atts(array(
'url' => '',
'width' => '400',
'alt' => 'Website screenshot',
), $atts, 'thumbalizr');
$image_url = mysite_thumbalizr_url($atts['url'], array(
'width' => $atts['width'],
'format' => 'jpg',
));
if (is_wp_error($image_url)) {
return '';
}
return sprintf(
'<img src="%s" alt="%s" loading="lazy">',
esc_url($image_url),
esc_attr($atts['alt'])
);
}
add_shortcode('thumbalizr', 'mysite_thumbalizr_shortcode');Use it in a post or page like this:
[thumbalizr url="https://example.com" width="600" alt="Example website thumbnail"]Do not treat a URL supplied by an editor as trusted merely because it is in WordPress content. Validate it, apply an allowlist if your use case requires one, and consider who is permitted to insert or change shortcode attributes. If the thumbnail is generated from visitor-supplied URLs, add stricter validation and abuse controls.
Choose capture options
Thumbalizr documents several parameters. Check the current option table and tier limits when implementing: valid ranges and defaults can differ by plan and may change.
| Option | What it controls | When to consider it |
|---|---|---|
width |
Output thumbnail width | Match the rendered image size and avoid downloading an unnecessarily large image. |
format |
JPG or PNG output | Choose based on image characteristics and browser needs. |
| JPEG quality | Compression quality for JPEG output | Balance file size and visual detail. |
size |
page or screen capture |
Use the mode that matches whether the desired result is a full page or a screen view. |
browser_width, browser_height |
Browser viewport dimensions | Use dimensions that resemble the context in which the thumbnail will be viewed. |
delay |
Wait time before capture | Allow client-rendered or late-loading page content time to appear. |
country |
Capture location | Use when the page varies by region, subject to plan availability. |
timestamp |
Requests a new thumbnail | Use when a fresh capture is needed rather than a previously generated image. |
Do not assume the largest width, longest delay, or a particular capture mode is best for every target. Larger output and longer waits can add transfer or processing time, while regional or viewport-specific rendering may change the result.
Handle queued and failed requests
The API response can indicate that work is queued, completed, or failed. Thumbalizr documents these response headers:
X-Thumbalizr-Status: values includeQUEUED,OK, andFAILED.X-Thumbalizr-Generated: generated date information.X-Thumbalizr-Error: an error reason when provided.
An image URL may not yield a completed screenshot immediately. For diagnostics, inspect the response status and headers from a server-side request or browser network panel, and check the vendor’s current behavior for queued results. Avoid assuming an empty or delayed image means the WordPress markup itself is broken.
Performance, reliability, and cost considerations
- Lazy-load below-the-fold images: the shortcode example sets
loading="lazy", which can defer image fetching until it is near the viewport. - Control image dimensions: request an output width appropriate to the layout and provide width/height attributes in your production markup to reduce layout movement.
- Do not generate signed URLs repeatedly without a reason: place shortcode rendering where it is needed and consider caching the resulting markup or URL according to your refresh requirements.
- Plan for asynchronous results: a queued capture may need another request or a later page load, depending on the documented service behavior. Build a fallback image or omit the thumbnail cleanly on failure.
- Review plan limits and cost: the reviewed documentation does not establish current pricing or quotas. Check Thumbalizr’s current plan information before estimating usage.
- Protect the signing secret: a signed image URL is visible to visitors, so avoid exposing sensitive target URLs or options in it. The secret itself must remain server-side.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Image is broken or blank | The request is queued or failed, the target URL is inaccessible, or the query signature does not match. | Inspect X-Thumbalizr-Status and X-Thumbalizr-Error; compare the encoded query and token generation with the vendor’s PHP sample. |
| Request reports an invalid token | The query string used to sign differs from the query sent, often due to encoding, parameter order, or changed values. | Build the query once and use those exact bytes both for signing and for the request. Follow the current documentation’s encoding requirements. |
| Thumbnail shows the wrong page area | size or viewport dimensions do not match the intended result. |
Compare page and screen, and set browser width and height deliberately. |
| Page content is missing | The page may render content after the capture begins. | Try an appropriate delay and check whether the target requires authentication or browser interaction. |
| Option is rejected or ignored | The option value may be invalid or unavailable on the current tier. | Recheck valid values and plan-specific limits in the current API documentation. |
| WordPress displays the shortcode literally | The shortcode registration code did not load, or the shortcode was entered in a context that does not process shortcodes. | Confirm the PHP code is active and use a shortcode-capable content area or render it through the theme. |
| PHP reports missing credentials | The constants were not defined in the active WordPress configuration. | Check the correct site’s configuration file and spelling, without printing the secret in a public error. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; its options also include full-page capture, element capture, viewport presets, custom CSS and JavaScript, waits, and caching. See the API documentation.
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}`);Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed, and responses identify the page verdict and billing status. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.
FAQ
Is there an official WordPress plugin?
Thumbalizr’s listed integrations do not show a WordPress-specific extension. The documented route covered here is a custom integration using its Embed API.
Can I put the Thumbalizr secret in a shortcode?
No. Keep it in server-controlled configuration and generate the signed URL in PHP.
Do I need to provide every API option?
No. The documentation says url is required; other values can use profile defaults.
Where can I confirm current limits?
Use Thumbalizr’s current API documentation and plan information. The documented ranges and option availability can vary by tier.
