Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sanskarsharma/thumbgen/llms.txt

Use this file to discover all available pages before exploring further.

Thumbgen is a lightweight Go web service that turns any publicly accessible image or video URL into a ready-to-use 200×200 PNG thumbnail — fully hands-off. You give it a source URL and a destination URL; Thumbgen downloads the media, generates the thumbnail, and uploads the result via HTTP PUT, all in a single API call. No temporary storage management, no client-side processing, and no proprietary upload target required.

​
Core Workflow

Every thumbnail request follows the same three-step pipeline:
  1. Download — Thumbgen fetches the source media from the download_url you provide and inspects the Content-Type response header to determine how to process it.
  2. Generate — Depending on the media type, Thumbgen resizes and crops the content to produce a 200×200 PNG thumbnail.
  3. Upload — The finished thumbnail is sent to your upload_url via an HTTP PUT request.
Because the upload step is a plain HTTP PUT, Thumbgen works seamlessly with S3 pre-signed URLs — generate a pre-signed PUT URL for your bucket, pass it as upload_url, and the thumbnail lands directly in S3 without any extra credentials or SDKs on the server.

​
Supported Media Types

Thumbgen handles two categories of media, each processed by a different backend.

​
Images

Images are processed using the disintegration/imaging Go library, which resizes and center-crops the source to fit the 200×200 canvas using a Catmull-Rom resampling filter.
MIME TypeFormat
image/jpegJPEG
image/pngPNG
image/gifGIF
image/bmpBitmap
image/svg+xmlSVG
image/tiffTIFF

​
Videos

Videos are processed using ffmpeg. Thumbgen extracts the first frame of the video, scales it to fit 200 pixels on the longest side, and then center-crops the result to 200×200.
MIME TypeFormat
video/mp4MPEG-4
video/3gpp3GPP
video/mpvMPV
video/x-flvFlash Video
video/quicktimeQuickTime / MOV
video/rawRaw video
video/x-msvideoAVI
video/x-ms-wmvWindows Media Video
video/webmWebM
The supported MIME type lists can be overridden at runtime using the SUPPORTED_IMAGE_CONTENT_TYPES and SUPPORTED_VIDEO_CONTENT_TYPES environment variables. See the Configuration page for details.

​
Output Format

Regardless of the input format or media category, Thumbgen always produces a 200×200 PNG file. The output image uses a transparent background (NRGBA with zero alpha) as the base canvas before the thumbnail is pasted onto it, so any letterboxing areas will be transparent rather than filled with a solid colour.

​
Upload Mechanism

Once the thumbnail is generated, Thumbgen performs a standard HTTP PUT request to the upload_url you specified in the request body. The raw PNG bytes are written directly to the request body. Any HTTP server that accepts a PUT with a binary body at a given URL is a valid target — this includes:
  • Amazon S3 (and S3-compatible stores) via pre-signed PUT URLs
  • Google Cloud Storage signed URLs
  • Any custom upload endpoint in your own infrastructure
If the upload destination returns a non-200 status code, Thumbgen treats it as an error and returns a 500 response to the caller.

​
Error Handling

Thumbgen returns structured JSON error responses for all failure conditions.
Status CodeTriggerResponse body key
400Malformed JSON body or missing download_url / upload_url fieldsmessage (or plain text for body-read failures)
422Download URL returned a non-2xx status, or the Content-Type is not a supported image or video typemessage
500Any unhandled panic — including a failed upload to upload_urlerror
The 500 responses are produced by recoveryMiddleware, which wraps every route and catches panics via a deferred recover() call. When triggered, it writes {"error": "There was an internal server error"} with an HTTP 500 status. This means any internal failure — such as the upload step returning a non-200 response — surfaces as a clean JSON 500 rather than an unhandled crash.

​
Web Frontend

Thumbgen ships with a small browser-based UI served at GET /. Open http://localhost:4499 in your browser to paste in a download URL and an upload URL and trigger thumbnail generation without writing any code — useful for quick manual tests during development. Static assets are served from the public/ directory under the /static/ path prefix.

​
Explore the Docs

Quickstart

Run Thumbgen locally and generate your first thumbnail in under 5 minutes.

API Reference

Full reference for the /thumbify endpoint, request fields, and response codes.

Deployment

Run Thumbgen with Go, Docker, or Docker Compose — and deploy to Cloudflare Containers.

Configuration

Customise supported MIME types and shell environment via environment variables.

Build docs developers (and LLMs) love

Get started for freeTalk to us