Thumbalizr API Authentication: Where to Find and Use Your API Key
Find your Thumbalizr API key and secret in the member section, then build an authenticated Embed API request without exposing your secret.
Thumbalizr says your API key and secret are in the member section after you sign up for an account. The official documentation does not specify dashboard clicks, so use the member section rather than relying on an assumed menu path. For website embeds, the documented Embed API puts the key in the request path and uses an MD5 token derived from the encoded query string plus your secret. Keep that secret on a server you control. Thumbalizr API documentation.
Find your API key and secret
- Sign up for a Thumbalizr account if you do not already have one.
- Open the member section and locate the API credentials. Thumbalizr calls these the API key and Secret; the Embed API documentation refers to the key as the Embed API key.
- Store both values in server-side configuration or a secrets manager. Do not put the secret in browser JavaScript, public HTML, a mobile app bundle, or a public repository.
The official docs do not establish a recovery, rotation, or dashboard navigation procedure. If you cannot find a credential or need to replace one, use Thumbalizr’s current account support channels rather than guessing at a menu or recovery flow.
How Thumbalizr Embed API authentication works
The documented request shape is:
https://api.thumbalizr.com/api/v1/embed/EMBED_API_KEY/TOKEN/?url=https%3A%2F%2Fwww.google.com%2F&mode=pageTo calculate TOKEN, build the query string, append the secret directly to that string, then take the lowercase hexadecimal MD5 digest:
query = "url=https%3A%2F%2Fwww.google.com%2F&mode=page"
token = MD5(query + secret)The query string’s exact bytes matter. Encode parameter values, especially the target URL, before hashing. Then send that same encoded query string in the request. Do not hash one representation and send another.
Runnable Node.js example
This example uses Node’s built-in crypto module and requires Node.js 18 or later for built-in fetch. Set THUMBALIZR_EMBED_KEY and THUMBALIZR_SECRET in the environment before running it. It writes the returned response to a file so you can inspect the result.
// save as thumbalizr.mjs
import { createHash } from 'node:crypto';
import { writeFile } from 'node:fs/promises';
const embedKey = process.env.THUMBALIZR_EMBED_KEY;
const secret = process.env.THUMBALIZR_SECRET;
if (!embedKey || !secret) throw new Error('Set THUMBALIZR_EMBED_KEY and THUMBALIZR_SECRET');
const params = new URLSearchParams({
url: 'https://www.google.com/',
mode: 'page',
});
const query = params.toString();
const token = createHash('md5').update(query + secret, 'utf8').digest('hex');
const endpoint = `https://api.thumbalizr.com/api/v1/embed/${encodeURIComponent(embedKey)}/${token}/?${query}`;
const response = await fetch(endpoint);
console.log('HTTP', response.status);
console.log('Thumbalizr status:', response.headers.get('x-thumbalizr-status'));
console.log('Thumbalizr error:', response.headers.get('x-thumbalizr-error'));
await writeFile('thumbalizr-result', Buffer.from(await response.arrayBuffer()));Run it from a shell with environment variables configured, for example node thumbalizr.mjs. The output file is intentionally named without assuming an image format: choose and verify the format using the API’s current options and response behavior.
Python implementation
The following Python 3 example uses only the standard library to construct and sign the request URL. It prints the URL for server-side use; because the URL contains a token, do not publish it if doing so would expose credentials or grant unintended access.
import hashlib
import os
from urllib.parse import urlencode
embed_key = os.environ["THUMBALIZR_EMBED_KEY"]
secret = os.environ["THUMBALIZR_SECRET"]
params = [("url", "https://www.google.com/"), ("mode", "page")]
query = urlencode(params)
token = hashlib.md5((query + secret).encode("utf-8")).hexdigest()
endpoint = f"https://api.thumbalizr.com/api/v1/embed/{embed_key}/{token}/?{query}"
print(endpoint)For a download from a Python service, use an HTTP client to request the printed endpoint and check the response headers before treating the body as a successful screenshot. Thumbalizr’s Python page also documents its library and Django integration; see Thumbalizr for Python and Django.
cURL request with a precomputed token
cURL does not calculate the documented token by itself. Generate the token in trusted code, then pass the resulting key, token, and encoded query to cURL. Keep the secret out of the command line and shell history.
curl --fail-with-body --get \
"https://api.thumbalizr.com/api/v1/embed/${THUMBALIZR_EMBED_KEY}/${THUMBALIZR_TOKEN}/" \
--data-urlencode "url=https://www.google.com/" \
--data-urlencode "mode=page" \
--dump-header thumbalizr-headers.txt \
--output thumbalizr-resultTHUMBALIZR_TOKEN must be computed from the exact query string sent. Since cURL’s --data-urlencode generates the encoding, make sure your token-generation code uses the same parameter order and encoding rules. A safer production pattern is to construct the query and token together in one server-side function, then make the HTTP request from that service.
Options and request construction
Thumbalizr says only url is required; omitted options use defaults set in your profile. The documentation lists options including width, format, JPEG quality, timestamp, size, delay, browser width and height, and country. Available values can depend on membership level. Check the current API documentation and your account settings before depending on a particular value or entitlement.
| Concern | What to do |
|---|---|
| Target URL | Include a complete URL and percent-encode it as a query parameter. Do not concatenate raw URLs containing & or other reserved characters into the query. |
| Optional parameters | Build the full query first, in a deterministic order; append the secret only after all parameters have been encoded. |
| Formats and quality | Use only values currently supported for your account. The documentation lists format and JPEG quality as options. |
| Capture sizing and timing | Width, size, browser dimensions, and delay are documented options. Check current allowed values and account limits. |
| Defaults | Omitted options use your profile defaults according to the documentation, so identical requests can depend on account configuration. |
For an embedded image, the Embed API is the documented choice. Thumbalizr warns that its older API should not be used for direct public webpage embedding unless the API key can be hidden from visitors, and recommends the Embed API instead. The Embed API still requires careful handling of its secret while generating tokens: generate the signed URL on a server if the secret must remain private.
Security checklist
- Keep the secret in server-side environment configuration or a secrets manager.
- Do not expose the secret in front-end code, public repositories, logs, or error reports.
- Do not assume the token makes a publicly rendered URL private; anyone who can inspect a page’s image URL can see that URL.
- Use HTTPS and avoid logging full signed URLs unnecessarily.
- Do not invent a credential rotation workflow: consult Thumbalizr’s current account support if you need recovery or replacement.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
X-Thumbalizr-Status: FAILED |
The screenshot request failed. The response may include X-Thumbalizr-Error with details. |
Read both response headers; correct the request or target problem described in the error before retrying. |
| Token rejected or request fails unexpectedly | The string hashed differs from the query sent: a parameter is missing, reordered, encoded differently, or changed after hashing. | Build the encoded query once, hash that exact string plus the secret, and send that same query unchanged. |
| Target URL appears malformed | The nested target URL was concatenated without percent encoding, so its punctuation is interpreted as outer query syntax. | Use a URL/query encoder for the url value. Avoid manual escaping. |
| Credentials are not found | The docs identify the member section but do not give a click-by-click path. | Sign in and inspect the member section; contact Thumbalizr support for account-specific recovery. |
| Image appears in development but not on a public page | A legacy endpoint or client-side credential handling may be inappropriate for public embedding. | Use the documented Embed API and keep the secret server-side while generating the request URL. |
| Requested size or feature is unavailable | Some options depend on membership level and profile defaults may affect omitted settings. | Check the live documentation and account configuration; do not rely on historical plan tables. |
Performance, reliability, and cost considerations
Authentication itself is a small hash calculation; the screenshot request and target page load determine most of the wait. Avoid generating repeated captures when a cached or stored image fits your use case. Set capture options deliberately, and do not retry a failed request in a tight loop. The documented response headers are useful for distinguishing queued, successful, and failed requests: X-Thumbalizr-Status can report QUEUED, OK, or FAILED, and X-Thumbalizr-Error can provide failure detail.
Do not assume current plan prices, quotas, or feature entitlements from old examples. The available options can depend on membership level; verify account-specific limits before estimating production cost. For reliability, handle non-success states explicitly, record request identifiers or relevant headers if provided, and use bounded retries with backoff only for failures that are safe to retry.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. Its API accepts a URL in one GET request and returns an image or PDF. See the ScreenshotNeo site and 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; each cleanup step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed. Response headers say which page verdict occurred and whether it was billed.
- An MCP server lets AI agents use
take_screenshot,get_page_info, andcapture_pdf. - The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.
Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.
FAQ
Is the API key the same as the secret?
No. The key identifies the Embed API account in the endpoint path; the secret is used to calculate the request token.
Can I put the secret in browser JavaScript?
Do not expose it there. Generate authenticated requests on a server when the secret needs to remain private.
Does every Thumbalizr request need every option?
No. The documentation says url is required and omitted options use profile defaults.
Where can I find Thumbalizr’s supported parameter values?
Use its current API documentation and account settings, because available values may depend on membership.
