Thumbnail API
Generate resized image thumbnails from remote HTTP or HTTPS image URLs. By default the endpoint returns the image directly from the same URL; add json=1 for a JSON response.
https://thumbnails.backends.co.uk/t/?i={image_url}
Use /t/ for generation and /docs for this reference.
Request Options
| Parameter | Default | Accepted values | What it does |
|---|---|---|---|
i |
Required | HTTP or HTTPS image URL | Remote source image to download and transform. |
w |
300 |
1 to configured max width |
Output width in pixels. The default configured maximum is 3000. |
h |
Same as w |
1 to configured max height |
Output height in pixels. If omitted, square-style modes use the width. |
q |
85 |
1 to 100 |
Output quality for JPEG and WebP. PNG output is lossless. |
f |
jpg |
jpg, jpeg, png, webp |
Output image format. jpeg is saved with a .jpg extension. |
json |
Off | 1, true, yes, on |
Return JSON metadata instead of the generated image bytes. |
Crop Modes
| Flag | Mode | Result |
|---|---|---|
| No crop flag | cover |
Fills the requested dimensions and crops overflow. If h is omitted, output is square. |
c_square |
cover |
Creates a square thumbnail using w for both width and height. |
c_fill |
cover |
Fills w by h, cropping where needed to preserve aspect ratio. |
c_fit |
contain |
Fits the entire image inside w by h, preserving aspect ratio. |
c_stretch |
resize |
Forces the image to exactly w by h. Aspect ratio may change. |
Responses
Image response
Without json, a successful request returns 200 with the generated image at the same /t/ URL.
JSON response
With json=1, the API returns success, thumbnailUrl, cached, width, height, mode, and format. The thumbnailUrl points back to the same endpoint without json.
Error response
Invalid requests return 400. Errors are plain text by default, or JSON when json=1 is present.
Limits
Source URLs must use http or https, return an image content type, and stay under the configured download size limit. Defaults are 3000x3000 maximum dimensions and 10485760 bytes for remote images.
Generated files are cached by the source URL and transformation options for one week. Image responses also send one-week public cache headers.
Examples
Square JPEG thumbnail
https://thumbnails.backends.co.uk/t/?i=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1500530855697-b586d89ba3ee&w=300&c_square=116:9 WebP thumbnail with JSON metadata
https://thumbnails.backends.co.uk/t/?i=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1500530855697-b586d89ba3ee&w=1280&h=720&c_fill=1&f=webp&q=80&json=1Fit entire image inside a PNG box
https://thumbnails.backends.co.uk/t/?i=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1500530855697-b586d89ba3ee&w=600&h=400&c_fit=1&f=pngStretch to exact dimensions
https://thumbnails.backends.co.uk/t/?i=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1500530855697-b586d89ba3ee&w=320&h=180&c_stretch=1