Thumbgen is a lightweight HTTP service that accepts a source media URL and a destination upload URL, downloads the media, generates a 200×200 PNG thumbnail, and PUT-uploads the result — all in a single request. The API is intentionally minimal: one endpoint does all the work. By default, the service listens onDocumentation 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.
http://localhost:4499. No authentication is required.
Base URL
http://localhost:4499 with your deployed domain when running Thumbgen in production (e.g. https://thumbgen.example.com).
Authentication
No authentication is required. Thumbgen is a self-hosted service assumed to run inside a trusted environment (a private network, a sidecar container, etc.).Because there is no built-in authentication, you should not expose Thumbgen directly to the public internet. Run it behind a reverse proxy (nginx, Caddy, AWS ALB, etc.) and apply network-level access controls if the service must be reachable outside a trusted boundary.
Endpoints
GET /
Serves the Thumbgen web UI (
public/index.html) with Content-Type: text/html; charset=utf-8. Open this in a browser to interact with the service visually. Also accepts HEAD requests.GET /static/*
Serves static assets from the
public/ directory. The /static/ path prefix is stripped before the file is looked up, so /static/app.js resolves to public/app.js.POST /thumbify
Generate and upload a thumbnail. Downloads media from
download_url, generates a 200×200 PNG thumbnail (image or video), and PUT-uploads it to upload_url. This is the core API endpoint.Request Format
All API requests to/thumbify must send a JSON body with the Content-Type: application/json header set.
download_url and upload_url) are required. Omitting either will return a 400 JSON error. Sending a malformed JSON body will return a 400 plain-text error (see Error Codes below).
Response Format
| Scenario | Status | Body |
|---|---|---|
| Thumbnail successfully generated and uploaded | 200 OK | (empty) |
| Malformed JSON body | 400 Bad Request | Plain-text Go error string (not JSON) |
Missing or empty download_url / upload_url | 400 Bad Request | {"message": "..."} |
| Non-2xx download URL or unsupported media type | 422 Unprocessable Entity | {"message": "..."} |
| Unexpected internal failure | 500 Internal Server Error | {"error": "..."} |
upload_url you provided before the response is returned.
On failure the response body is either plain text (for the malformed-JSON 400) or a JSON object containing either a message field (400 missing-fields and 422 errors) or an error field (500 errors).
Error Codes
| Status | Cause | Body format |
|---|---|---|
400 | Request body is not valid JSON | Plain text — the raw Go parse error |
400 | download_url or upload_url is absent or empty | {"message": "download_url or upload_url key not present in request data"} |
422 | download_url returned a non-2xx HTTP status code | {"message": "download url returned N status code"} |
422 | Downloaded content has an unsupported Content-Type | {"message": "Un-supported content type"} |
500 | Unrecoverable panic during processing (e.g. upload failure) | {"error": "There was an internal server error"} |