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 -OG "https://cloud.thumbrella.dev/thumb.jpeg" \
  --data-urlencode "url=https://demo.thumbrella.dev/media/golden-gate.exr" \
  --header "Authorization: Bearer tbr_e_3QnzBcWx7KpRmYT2000example"

Token Limitations

Token limits restrict how a token can be used, helping reduce the risk of publishing it in an interactive web application. The dashboard also breaks down usage by token so you can see which tokens are active.

Manage limits on the user dashboard. Choose Add limit next to a token to add an editable panel. Only active limits are shown; use a panel’s close icon to remove it. Choose Save to apply your changes or Cancel to discard them. Clearing a text field leaves its panel visible until you save; an empty field disables that filter or setting.

• Origin Filter requires the HTTP Origin header to match a case-insensitive regular expression, such as mydomain\.com$. Browsers set this header, but direct HTTP clients can spoof it.
• CORS sets the Access-Control-Allow-Origin response header to an origin, such as https://example.com, or * to allow any origin. Browsers enforce CORS; direct HTTP clients do not. Removing this limit or leaving it empty restores the default *.
• Media URL Filter has Include and Exclude fields in one panel. URLs must match the include pattern and must not match the exclude pattern. Both use case-insensitive regular expressions, such as mydomain\.com or /gallery. Either field can be left empty; exclusions take priority. Removing the panel clears both filters.
• Quota caps the token at a percentage of the account’s quota limits. Account usage still combines all tokens; this does not reserve quota for one token. Removing this limit restores 100%.
• Expires automatically disables the token on a chosen date. Use the calendar or a relative-date shortcut to set it. To stop expiration, remove the limit. An expired token can be used again by changing or removing its expiration date.
• Disable pins prevents the token from creating or refreshing pinned cache entries. New tokens allow pins by default. Removing this limit allows pinning again; disabling pinning does not delete existing pins. Pin lifetime is controlled by the account’s maximum cache TTL, not the token.
• Throttle requests applies stricter throttling than the regular free account limits, helping slow runaway clients before they consume the quota. Add or remove this panel to enable or disable the stricter throttling.

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.