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.

Before generating a thumbnail, Thumbgen makes a GET request to the download_url provided in the API call and inspects the Content-Type response header to determine how the file should be processed. If the detected type matches an entry in the supported images list, the file is decoded and resized using the imaging library. If it matches an entry in the supported videos list, a single frame is extracted with ffmpeg. If neither list matches, the request is rejected.

​
Default Supported Types

MIME TypeFormat
image/jpegJPEG
image/pngPNG
image/gifGIF
image/bmpBMP
image/svg+xmlSVG
image/tiffTIFF
If the Content-Type header returned by the download URL does not match any entry in either the image or video list, Thumbgen returns HTTP 422 with the response body:
{"message": "Un-supported content type"}
Check that the origin server sets an accurate Content-Type header and that the MIME type is included in the active supported list.

​
Customising Supported Types

Both the image and video MIME type lists can be fully replaced at runtime via environment variables, without any code changes or rebuilds. Set SUPPORTED_IMAGE_CONTENT_TYPES to a JSON array of MIME strings to override the image list: 
# Accept only JPEG, PNG, and WebP images
SUPPORTED_IMAGE_CONTENT_TYPES='["image/jpeg","image/png","image/webp"]' go run main.go
Set SUPPORTED_VIDEO_CONTENT_TYPES to a JSON array of MIME strings to override the video list: 
# Accept only MP4 and WebM videos
SUPPORTED_VIDEO_CONTENT_TYPES='["video/mp4","video/webm"]' go run main.go
Both variables can be combined, and they work identically in Docker: 
docker run -d -p 4499:4499 \
  -e SUPPORTED_IMAGE_CONTENT_TYPES='["image/jpeg","image/png"]' \
  -e SUPPORTED_VIDEO_CONTENT_TYPES='["video/mp4","video/webm"]' \
  thumbgen:v0
When either variable is set it replaces the entire built-in default — it does not merge with it. To retain existing defaults while adding a new type, include the original values in your custom array. See Environment Variables for the full reference on these variables, including the valid JSON requirement.

​
How Type Detection Works

  1. Thumbgen receives a POST /thumbify request containing a download_url.
  2. It issues a GET request to that URL and reads the Content-Type header from the HTTP response.
  3. The raw header value (e.g. image/jpeg or video/mp4) is compared against the active image list first, then the active video list.
  4. On a match in the image list, the response body is streamed to a temporary file and passed to the imaging library for resizing.
  5. On a match in the video list, the download_url is passed directly to ffmpeg, which fetches and decodes the video itself to extract a single frame.
  6. If neither list matches, Thumbgen returns HTTP 422 immediately without downloading the file further.
AWS S3 pre-signed URLs (and equivalent signed URLs from other object-storage providers) return the correct Content-Type header that was set when the object was uploaded. As long as the object was stored with an accurate content type — for example, image/jpeg for a JPEG photo — Thumbgen will detect and process it correctly without any extra configuration. If thumbnails are unexpectedly returning 422, verify the Content-Type metadata on the S3 object itself, as it may have been uploaded without one (defaulting to application/octet-stream).

Build docs developers (and LLMs) love

Get started for freeTalk to us