Cloud

Thumbrella Cloud is the hosted version of the service. It runs the same open source Thumbrella server on managed infrastructure with a global edge cache and access to high-quality rendering backends. There is nothing to deploy or maintain.

Auth Tokens

When an account is created, it will immediately come with an authentication token. This token is used as the connection string, typically assigned to the TBR_CONNECT environment variable.

export TBR_CONNECT=tbr_e_3QnzBcWx7KpRmYT2000example

This token is the value to use as the connection string. Either assign it to $TBR_CONNECT or provide it as an optional argument when constructing a Client object.

Accounts can create additional tokens that share the limits and quotas for the account. Each token can be independendently disabled, rotated, and managed.

All tokens have a rich set of limitations that can be applied. This allows generating tokens that can be used in interactive javascript applications with protections against running out the account’s quotas.

Note

By default, authentication tokens come with unrestricted access to the account’s resources. Treat these as protected secrets; avoid placing them into source control. Use .env files or platform secrets to apply them to your offline code. If these tokens leak publically, strongly consider rerolling them, in the user dashboard pages.

When making direct HTTP requests to Thumbrella Cloud the authentication token is sent as a bearer authentication HTTP Header. With curl that will look like this.

curl -G "https://cloud.thumbrella.dev/thumb.jpeg" \
  --data-urlencode "url=https://demo.thumbrella.dev/media/golden-gate.exr" \
  --header "Authorization: Bearer tbr_e_3QnzBcWx7KpRmYT2000example" \
  --output thumb.jpeg

Token Limitations

Each token has a set of limitations that can be edited at any time on the user dashboard. These limitations restrict how the token can be used, making it less risky to put into publishable locations, like an interactive web application.

On the dashboard, the usage and quota information is divided into each token, to allow simpler tracking of which tokens are being actively used.

These are editable on the user dashboard. Each token has a limitations dropdown that allows editing and committeng each of these fields.

• Origin Regex When set, this is a regular expression that requires matching the http header Origin. This is reliably set by web browsers, but be aware can be easily spoofed by direct http clients. Examples would be string like mydomain\.com$. The regular expression is matched case insensitively.
• Cors This is the header value used for thumbnail requests. This is respected by well behaved browsers to prevent using Thumbrella resources from websites not allowed. Be aware this is easy to ignore for direct HTTP clients. If empty this is equivalent to * which allows any browser to generate thumbnails from any website.
• Media Url Regex Include and Media Url Regex Include. This restricts the media urls that can be used to generate thumbnails. There is a separate include and exclude regular expression. If either is unset they will not prevent any urls from used. These two fields can be set indenpendently, or both combined. Examples would be like mydomain\.com or /gallery. The regular expression is matched case insensitive.
• Quota restricts the token to use only a percentage of the accounts quota limits. Each token defaults to 100. Be aware that the account quota is based on the combined usage of all tokens. But this setting allows a single token to use no more than a fixed percentage of the account’s total data.
• Expires allows a token to automatically expire after a given date. This value can be set, cleared, or changed at any time. If the expiration date passes, the token can reenabled and a new expiration set.
• Throttle all accounts start to throttle requests when there are surges of activity within a short period. Slowing down these requests assists runaway clients from absorbing all the quota in a short period of time. Enabling this value will start to throttle requests using this token at a more aggressive level than regular free account limits.

Usage

See the pricing page for current quotas and limits on cloud account types.

Render counts track freshly generated thumbnails. Results served from the edge cache do not consume render quota.

Cache limits describe how much thumbnail data Thumbrella stores in its global edge network. Thumbnails served from the edge are instant worldwide.

When the render quota is exhausted the server continues to return thumbnails, placeholder images rather than hard errors. Results still arrive in the same shape; only the source field and image content change. Applications do not need special handling for quota exhaustion.

Limits

Accounts have a daily usage limit. This limit only counts against rendered thumbnails. Cached, missing, or simple requests do not count towards this quota.

Ten percent of the daily limit will also be used to restrict the number of thumbnails an account can generate within any given hour.

When accounts reach their limit for a given time period they begin returning simple placeholder results for their media. They can continue to return precached results without consuming quota.

The API encourages batching multiple requests into a single HTTP operation. The usage and quota tracking is based on each thumbnail requested, not the number of HTTP operations. See the HTTP API for batch request details.

When the cloud server notices an account rapidly generating requests it will throttle the requests. Slowing them down so they do not run into the hourly or daily limits unintentionally.

Accounts that continue to overload the server will eventually start receiving HTTP 429 results, meaning the server is “Too Busy” to handle additional requests.

Global Cache

Thumbrella Cloud maintains a distributed edge cache shared across all users. When any client requests a thumbnail for a URL that has already been rendered, the cached result returns immediately from a nearby edge node, no download or render required, and no render quota consumed.

This shared pool means popular URLs benefit most. A widely used CDN asset might already be cached by thousands of accounts before your application ever requests it. Paid accounts receive more cache storage and a longer TTL, keeping a broader set of URLs warm between accesses.

The cache TTL controls how long Thumbrella trusts a previously rendered thumbnail without re-checking the origin. Once expired, Thumbrella revalidates the remote URL and re-renders only if the content has changed. Media that hasn’t changed returns as not_modified at no render cost.

Client libraries provide an additional local cache layer on top of the server cache, so frequently accessed URLs can resolve without any network call at all. See the Client docs for details.

Hybrid Servers

The Thumbrella Cloud server can be used to extend standalone self hosted Thumbrella servers. These can be used together for caching and to simplify the handling of more complicated media formats.

See the server hybrid section for configuring the standalone server this way.

Demo Server

At any point, you can experiment with a client using the Thumbrella Demo site. This provides free access to thumbnails for the media hosted in the demo gallery. No account is required.

Instead of setting the connect string to an authentication token, set it to the url of the demo site. This is the same as connecting clients to a custom, self-hosted server.

export TBR_CONNECT=https://demo.thumbrella.dev

uvx thumbrella-client basic https://demo.thumbrella.dev/media/neon-block.png

AI Platform Servers

Note

Coming soon

The Thumbrella server will be available on AI compute platforms, like fal.ai and Replicate.

Platforms like this can be an excellent use case for applications already written on these platforms. Thumbrella runs without the GPU hosts these platforms typically provide, making its usage cost relatively low.

Thumbrella does not collect any payment for usage on these platforms. The The Thumbrella Cloud platform is designed to be more cost-efficient than these platforms.

These platforms can also be extended with Thumbrella Cloud to take advantage of additional server side caching. Look for the optional token parameter on these requests. The global Thumbrella Cloud cache can significantly reduce the processing needed on these platforms and speed up the results.

Terms of Service

Thumbrella Cloud is provided on a best-effort basis. Uptime depends on upstream infrastructure and is not guaranteed.

Administrators may throttle, suspend, or permanently disable accounts at their discretion. This includes accounts that intentionally abuse the service, degrade performance for other users, or attempt to circumvent limits by creating multiple accounts. Users who repeatedly create accounts after suspension may be blocked from creating new accounts through IP ranges, email patterns, or other technical measures.

Free accounts share pooled resources and may experience delays or cold starts under load.

Usage is subject to hourly and daily limits. Requests are gradually throttled as limits are approached. The dashboard shows daily usage, but results may be delayed by several minutes before appearing.

Paid accounts subscribe monthly. The allows extended quotas and priority access. Upon subscription, quotas increase within minutes. Cancellations remain active through the end of the current pay period, after which accounts return to free-tier limits.

Extended outages that materially impact service may, at administrator discretion, result in account credits toward future payments. An account’s credits will not exceed the current period’s subscription amount. Refunds are not provided; credits are the sole remedy for service interruptions if necessary.

The service may need to disable file formats or features that pose risk to the platform. While the goal is to expand supported formats over time, no specific format is guaranteed to remain available.

These terms and the privacy policy may be updated at any time. Continued use of the service after changes constitutes acceptance.

Privacy Policy

Thumbrella Cloud avoids storing personally identifiable information. In practice this means.

• All user information is handled through Clerk.
  • Thumbrella only stores the internal Clerk account id.
    • No email, no user names, or any other PII stored by Thumbrella Cloud.
  • Clerk triggers webhooks when account status has changed.
  • Clerk keeps a JWT cookie in the browser session.
  • No Clerk scripts or components will be loaded until login actions are made.
• Cache information is partitioned for each account.
  • No sharing of cache information across accounts.
  • Media served with “do not cache” or “private” HTTP headers are not cached.
  • Only sanitized urls are stored, no query parameters tracked.
• Cloudflare’s “insights analytics” are used on the site.
  • Excludes visitor information from the EU.
  • Information is anonymous and not associated with any accounts or api usage.