FAQ

What media types are supported?

Thumbrella supports over 100 media formats across several categories:

Kind	Count	Examples
Image	19	JPEG, PNG, WebP, AVIF, GIF, TIFF, BMP, HEIC, JP2, JXL, ICO, PSD, PPM, TGA
Photograph	27	RAW, DNG, EXR, HDR, CR2, NEF, ARW, ORF, RW2, PEF, SRW, RAF, 3FR, MEF
Video	14	MP4, MOV, MKV, AVI, FLV, TS, M4V, 3GP, OGV, WMV, MPEG, WebM
3D Geometry	26	OBJ, GLTF, GLB, STL, FBX, USDZ, IGES, DAE, PLY, 3DS, VRML
Document	6	DOCX, PPTX, ODT, XLSX, ODS, ODP
Audio	6	MP3, FLAC, OGG, M4A, AAC, WAV
Vector	1	SVG

Thumbrella classifies every format into a kind and canonical extension and generates a standard mime type for each thumbnail.

The server does require external, optional subcommands for rendering some file formats (notably 3D models and document formats). Run thumbrella formats to see which formats are available in your environment.

What is the difference between Cloud and self-hosted?

Thumbrella Cloud is the hosted service, it supports all available file formats and includes a globally distributed edge cache that improves performance for users worldwide. The architecture is efficient and lean, making it economic and viable for free use cases. Paid subscriptions are available for more resources.

A self-hosted server has other advantages. It can run in offline environments and handle private resource, are not publicly available. There are no usage limits when self-hosting; unlimited renders, unlimited cache, no rate throttling.

I don’t need a server, I just want to generate thumbnails from files.

The server command line has a thumb subcommand for this exact purpose. The executable is a single, static binary that runs without difficulty. It is packaged in several formats that make running it straightforward, even without installing anything.

npx @thumbrella/server thumb my_cool_video.mp4 my_cool_thumbnail.jpeg

Is caching supported?

The HTTP protocol has excellent standards for cache control. Thumbrella takes advantage of all of these. Both servers and client libraries can optionally store thumbnail results in persistent caches.

The server handles HTTP headers like Cache-Control, ETag, and Last-Modified`.

Caching at both levels is the primary way Thumbrella is fast and efficient. When using Thumbrella Cloud, cached results do not count against quota and usage.

The returned Result structure contains a cache value when encodes everything the server needs to know about caching. See more details in the server caching section.

Do I need a client library, or can I use HTTP directly?

No client library is needed. The HTTP API is intentionally simple, a single curl call gets you a JPEG thumbnail:

curl http://localhost:3114/thumb.jpeg \
  --data-urlencode "url=https://demo.thumbrella.dev/media/raw-canon.cr2" \
  --output thumb.jpeg

Client libraries assist with caching, streaming, batching, error recovery, and framework components. These can be more complicated with simple HTTP clients, but the core API works with any HTTP tool.

What size are the thumbnails?

Thumbnails are JPEG images, typically 5 KB to 10 KB each with a fixed resolution of 250x200. Quality is tuned for fast loading and visual recognizability, they are low quality.

You cannot customize the resolution, format, or compression level. The output is opinionated and consistent by design. The Thumbnail Output section has details on the resulting thumbnail image.

How fast is it?

For cached results: instant (no network round-trip needed if the client cache is warm). For fresh renders on Thumbrella Cloud: typically under 500 ms for images, most videos thumbnail in under one second. Complex 3D renders can take longer. The demo gallery shows render times and performance for a variety of files.

Can I use Thumbrella in a commercial product?

Yes. The server and client libraries are licensed under Apache 2.0, which encourages commercial use, modification, and distribution with minimal restrictions. You can embed the server, fork the code, or use Thumbrella Cloud in a paid product.

Does Thumbrella support authentication for private servers?

Yes. Set a handshake secret on your self-hosted server, and clients must include it in every request. For Thumbrella Cloud, your auth token authenticates you. The server itself fetches remote URLs, if your media requires HTTP authentication, include credentials in the URL.

What happens when I hit my rate limit?

When a Cloud account reaches its daily or hourly limit, the server continues to return results, but thumbnails are replaced with placeholder images instead of rendered content. Cached results continue to work normally. The status field in the result will indicate the state. Your application does not need special failure handling; the shape of every response is the same.

Can I run Thumbrella behind a reverse proxy?

Yes. The server binds to a single port (default 3114) and works well behind nginx, Caddy, or any HTTP reverse proxy. Set TBR_PORT to change the listen port. There are no WebSocket or long-poll requirements, it’s plain HTTP.

Does Thumbrella handle animated images?

Thumbnails are always single, still JPEGs. Thumbrella does handle animated GIFs, video files, and other animated formats like APNG. When handling video formats Thumbrella will select a single representative frame. Thumbrella is a thumbnail service, not a media transcoder or optimizer.

Where do I report bugs or request features?

General discussion is on the GitHub Discussions page.

File issues on the relevant GitHub repository: server, clients, or website.

Is there a free host I can try without installing anything or registering?

Yes. The demo gallery runs Thumbrella with a curated set of media files. This can only server media from the demo website. Use the url as a connect string for any client:

export TBR_CONNECT=https://demo.thumbrella.dev
npx @thumbrella/server thumb https://demo.thumbrella.dev/media/neon-block.png out.jpg