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.

POST /thumbify is the core endpoint of Thumbgen. It accepts a source media URL (download_url) and a destination upload URL (upload_url). Thumbgen downloads the source file, inspects its Content-Type header to determine whether it is an image or a video, generates a 200×200 PNG thumbnail (cropping and resizing as needed), and then PUT-uploads the resulting PNG to the destination URL — all before returning a response to the caller.

​
Endpoint

POST /thumbify

​
Headers

HeaderValueRequired
Content-Typeapplication/json✅ Yes

​
Request Body

​
download_url
string
required
The publicly accessible URL of the source image or video. Thumbgen issues a GET request to this URL and inspects the Content-Type response header to decide how to process the file.
  • Image — downloaded to a temporary file and resized/cropped to 200×200 PNG using the imaging library.
  • Video — ffmpeg extracts the first frame and crops it to 200×200 PNG.
The request will fail with 422 if this URL returns a non-2xx status code or if the content type is not supported.
​
upload_url
string
required
The destination URL where the generated 200×200 PNG thumbnail will be PUT-uploaded. Any URL that accepts an HTTP PUT request with the file body works here — AWS S3 pre-signed PUT URLs are a common choice.
upload_url works perfectly with AWS S3 pre-signed PUT URLs. Generate a pre-signed URL for your target S3 object with PutObject permissions, pass it as upload_url, and Thumbgen will upload the thumbnail directly to S3 — no extra credentials needed.

​
Response

​
Success — 200 OK

When the thumbnail has been successfully generated and uploaded to upload_url, Thumbgen returns HTTP 200 with an empty body. You can consider the upload complete as soon as you receive the 200 response. 
HTTP/1.1 200 OK

​
Error Response Shape

Error response bodies vary by status code:
  • 400 — malformed JSON body: plain text containing the raw Go JSON parse error (not a JSON object).
  • 400 — missing fields: JSON object with a message field.
  • 422: JSON object with a message field.
  • 500: JSON object with an error field.
​
message
string
Human-readable description of the error. Present on 400 (missing-fields) and 422 responses.
​
error
string
Human-readable description of an internal server error. Present on 500 responses only.

​
Error Responses

​
400 Bad Request — Malformed JSON body

Returned when the request body cannot be parsed as JSON. The response body is plain text (not JSON) — it contains the raw Go error string produced by the JSON parser. This response is not a JSON object and does not contain a message key. 
invalid character 'x' looking for beginning of value

​
400 Bad Request — Missing or empty fields

Returned when the body is valid JSON but download_url or upload_url is absent or an empty string. This response is a JSON object. 
{
  "message": "download_url or upload_url key not present in request data"
}

​
422 Unprocessable Entity — Download URL returned non-2xx

Returned when Thumbgen successfully contacted download_url but received a non-2xx HTTP status code (e.g. 404, 403). 
{
  "message": "download url returned 404 status code"
}
The actual status code from the upstream request is interpolated into the message.

​
422 Unprocessable Entity — Unsupported content type

Returned when the file at download_url was downloaded successfully but its Content-Type is neither an image nor a video type that Thumbgen supports. 
{
  "message": "Un-supported content type"
}

​
500 Internal Server Error

Returned when an unexpected panic or unrecoverable error occurs during processing — for example, when the PUT upload to upload_url returns a non-200 status. The recovery middleware catches the panic and writes this response before closing the connection. 
{
  "error": "There was an internal server error"
}

​
Examples

curl -X POST http://localhost:4499/thumbify \
  -H 'Content-Type: application/json' \
  -d '{"download_url": "https://example.com/photo.jpg", "upload_url": "https://my-bucket.s3.amazonaws.com/thumbnail.png?AWSAccessKeyId=...&Signature=...&Expires=..."}'

Build docs developers (and LLMs) love

Get started for freeTalk to us