Fast thumbnails for
online media.

For Node.js, Deno, Bun, and other JavaScript runtimes without a DOM, start with the JavaScript client. Use its Client API when your application needs to control requests, caching, batching, or streaming directly.

• Zero runtime dependencies, only needs fetch
• Runs in Node 18+, Deno, Bun, and modern browsers
• Optional <tbr-thumb> element for browser environments
• Single call efficiently processes multiple thumbnails in parallel
• Stream async results as the server renders thumbnails
• Persistent client caching integrates with server and HTTP
• Placeholders for failures, even if disconnected or misconfigured
• Load easily into sharp and other image libraries
• Typed results with simple media metadata
• Thumbrella server supports 100+ formats

//  Install with: `npm install @thumbrella/client`  //

import { Client } from "@thumbrella/client";

// Connect to server, defaults to $TBR_CONNECT with no argument.
const tbr = await new Client("http://localhost:3114").verify();

// Stream results as they complete
for await (const result of tbr.stream([
  "https://demo.thumbrella.dev/media/padres-stereo.exr",
  "https://demo.thumbrella.dev/media/golden-gate.exr",
])) {
  console.log(result.url, result.status);
}

The source comes with several starting point examples. See the client documentation for more details and information.

• examples/element.html Use the <tbr-thumb> element in a small, fixed gallery.
• examples/browser.html Stream multiple thumbnails as they render through the Client API.

For Python applications, start with the Python client. It uses requests for blocking calls and optionally aiohttp for asynchronous streaming results.

• Persistent client caching integrates with server and HTTP
• Single call efficiently processes multiple thumbnails in parallel
• Stream async results as the server renders thumbnails
• Load easily into PIL, Qt, Pygame, and others
• Placeholders for failures, even if disconnected or misconfigured
• Typed results with simple media metadata
• Thumbrella server supports 100+ formats

##  Install with: `uv add thumbrella-client`  ##

import thumbrella

# Connect to server and generate a thumbnail.
tbr = thumbrella.Client()
result = tbr.thumb("https://demo.thumbrella.dev/media/blue-scooter.fbx")
print(result.status, len(result.media.thumbnail), "bytes")

# Pillow can decode from a zero-copy buffer.
from PIL import Image
img = Image.open(result.media.thumbnail.io)

The source comes with several starting point examples. See the client documentation for more details and examples.

• examples/basic.py Download a thumbnail from a single url.
• examples/stream.py Stream multiple thumbnails as they render.
• examples/collage.py Assemble thumbnails from multiple sources into a single grid image.

For Rust applications, start with the Rust client. It provides high-level caching, error control, and typed results. By default it uses asynchronous calls with reqwest and tokio; the blocking feature provides a blocking interface for simpler environments.

• Async-first with reqwest (rustls TLS)
• Minimal dependencies, reqwest, serde, base64, thiserror
• Stream async results as the server renders thumbnails
• Single call efficiently processes multiple thumbnails in parallel
• Persistent client caching integrates with server and HTTP
• Placeholders for failures, even if disconnected or misconfigured
• Typed results with simple media metadata
• Thumbrella server supports 100+ formats

//  Install with: `cargo add thumbrella-client`  //

use thumbrella_client as thumbrella;

#[tokio::main]
async fn main() -> Result<(), thumbrella::Error> {
    let tbr = thumbrella::Client::new(None);
    tbr.verify().await?;

    // Get result and write thumbnail to jpeg file
    let result = tbr.thumb("https://demo.thumbrella.dev/media/game-level.png").await?;
    if let Some(media) = &result.media {
        println!("{} bytes  {}", media.thumbnail.len(), media.kind);
        std::fs::write("thumb.jpg", media.thumbnail.bytes())?;
    }

    Ok(())
}

The source comes with several starting point examples. See the client documentation for more details and examples.

• examples/basic.rs Download a thumbnail from a single url.
• examples/stream.rs Stream multiple thumbnails as they render.

The direct HTTP requests are designed to be usable without rich clients. This can work from any language with any HTTP library. Also from command line tools like curl or wget.

• Efficiently processes multiple thumbnails in parallel
• Stream batch results with newline-delimited JSON (ndjson)
• Every request results in a valid image or placeholder
• Server provides advanced HTTP caching support
• Thumbrella server supports 100+ formats

curl -OG "http://localhost:3114/thumb.jpeg" \
  --data-urlencode "url=https://demo.thumbrella.dev/media/harbor-trucks.mp4"

To interact with Thumbrella Cloud, register online for a quick and free account. Then add the token into the Authorization header.

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"

For most applications, prefer one of the language client libraries. They provide caching, result handling, and convenient batching or streaming APIs.

See the HTTP API documentation for batch requests, streaming, authentication, and result formats. See the client API documentation for the higher-level alternatives.