Get Started with Thumbgen: Generate Your First Thumbnail

By the end of this guide you will have Thumbgen running on your local machine, fired off your first /thumbify request with a real image or video URL, and confirmed that a 200×200 PNG thumbnail has been uploaded to your chosen destination. The whole process takes less than 5 minutes.

Check prerequisites

Thumbgen requires Go 1.14 or later and ffmpeg (for video thumbnails). Verify both are available before continuing.

go version

ffmpeg -version

You should see version output for each command. If either is missing:

Go — download the installer from go.dev/dl.
ffmpeg — install via your system package manager (e.g. brew install ffmpeg on macOS, apt install ffmpeg on Debian/Ubuntu) or grab a static build from ffmpeg.org.

Prefer containers? You can skip the Go and ffmpeg installs and run Thumbgen with Docker instead — see the Deployment guide. The Docker image is based on Alpine Linux and bundles ffmpeg automatically.

Clone and start the service

Clone the repository and start the server with go run:

git clone https://github.com/sanskarsharma/thumbgen.git
cd thumbgen
ENV=LOCAL go run main.go

You should see output similar to:

2024/01/01 12:00:00 Listening on :4499...
2024/01/01 12:00:00 Frontend available at: http://localhost:4499
2024/01/01 12:00:00 API endpoint: http://localhost:4499/thumbify

Thumbgen is now listening on port 4499.

The ENV=LOCAL prefix is important when running outside Docker. Thumbgen uses the ENV variable to decide which shell to invoke when running ffmpeg commands — bash for local development and ash (the Alpine shell) inside the Docker container. Without ENV=LOCAL, video thumbnail generation will fail on systems that do not have ash available.

Generate a thumbnail

With the service running, send a POST request to /thumbify. You need to provide two fields:

Field	Type	Description
`download_url`	string	Publicly accessible URL of the source image or video to thumbnail.
`upload_url`	string	HTTP PUT-accessible URL where the finished 200×200 PNG will be sent.

curl -X POST http://localhost:4499/thumbify \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://example.com/photo.jpg", "upload_url": "https://your-bucket.s3.amazonaws.com/thumb.png?presigned-params"}'

Thumbgen will:

Download photo.jpg from the source URL.
Detect the image/jpeg content type and process it with the imaging library.
Resize and crop the image to 200×200 pixels.
PUT the resulting PNG to your upload_url.

The same request works for video URLs — just point download_url at an .mp4 or any other supported video format and Thumbgen will use ffmpeg to extract and crop the first frame instead.

Using Amazon S3 as your upload destination? Generate a pre-signed PUT URL for your target object (e.g. with the AWS CLI or SDK), paste it in as upload_url, and the thumbnail will land directly in your bucket — no additional AWS credentials needed on the Thumbgen server.

# Example: generate a 15-minute pre-signed PUT URL with the AWS CLI
aws s3 presign s3://your-bucket/thumb.png --expires-in 900 \
  --region us-east-1 \
  --http-method PUT

Confirm the upload

If the request succeeds, Thumbgen returns an HTTP 200 with an empty body, and the 200×200 PNG thumbnail is now available at your upload_url destination.Check your upload target to verify:

S3 / GCS bucket — browse to the object in the console or download it with the CLI.
Custom endpoint — inspect your server logs or storage to confirm the PUT was received.

If Thumbgen encounters an error it returns an appropriate HTTP status code with a JSON body:

400 — malformed JSON or missing download_url / upload_url; body contains a "message" field (or plain text for body-read failures).
422 — the download URL returned a non-2xx status, or the content type is not supported; body contains {"message": "..."}.
500 — an internal failure such as a non-200 response from the upload target; body contains {"error": "There was an internal server error"}. This response is generated by Thumbgen’s recoveryMiddleware, which catches panics from any route handler.

Try the Web UI

Prefer a point-and-click experience? Open http://localhost:4499 in your browser while the service is running. The built-in web frontend lets you paste a download URL and an upload URL directly into a form and trigger thumbnail generation without writing any curl commands — ideal for a quick sanity check during development.

Next Steps

Read the full API Reference for request/response schemas and all status codes.
Learn about Deployment options including Docker, Docker Compose, and Cloudflare Containers.
See the Configuration page to customise supported MIME types via environment variables.

Get Started

Deployment

Configuration

Documentation Index

​Try the Web UI

​Next Steps

Build docs developers (and LLMs) love

Try the Web UI

Next Steps