Image API

One endpoint that turns any Pexels photo into a resizable, hotlinkable URL. No key, no signup — just point an img tag at it.

Quick start

Every photo on Imagisum is served from a single route. Give it an id and the dimensions you want:

<img
  src="https://imagisum.vercel.app/image?id=1181671&width=800&height=450"
  width="800"
  height="450"
  alt="Free stock photo"
/>

Prefer the UI? Open any photo, set the size, and copy the ready-made snippet. Browse photos.

Parameters

GET /image

Param	Type	Description
idRequired*	number	Pexels photo id. Every photo page shows it in the URL.
randomRequired*	0 \| 1	Returns a different photo on every request. Use instead of `id`.
queryOptional	string	Narrows random mode to a subject, e.g. `nature`, `office`.
widthOptional	16–6000	Output width in pixels. Alias: `w`.
heightOptional	16–6000	Output height in pixels. Alias: `h`.
fitOptional	crop \| contain	`crop` fills the box and trims overflow (default). `contain` fits inside it.
formatOptional	auto \| jpg \| png \| webp \| avif	Output encoding. `auto` lets the CDN decide. Alias: `fm`.
qOptional	1–100	Compression quality for lossy formats. Defaults to 80.
dprOptional	1–3	Multiplies the output size for retina displays.
blurOptional	0–100	Gaussian blur. Useful for background art and loading states.
grayscaleOptional	0 \| 1	Strips all colour from the output.
fp-xOptional	0–1	Horizontal crop anchor, where 0 is the left edge. Only applies when cropping.
fp-yOptional	0–1	Vertical crop anchor, where 0 is the top edge. Only applies when cropping.
downloadOptional	0 \| 1	Sends `Content-Disposition: attachment` so browsers save the file.

* Pass either `id` or `random=1` — one of the two is required.

Custom sizes

Width and height are independent. Give both and the photo is cropped to fill that exact box; give one and the other scales to keep the original ratio.

/image?id=1181671&width=400            → 400px wide, ratio preserved
/image?id=1181671&width=400&height=400 → square, cropped to fill
/image?id=1181671&width=400&height=400&fit=contain → square, letterboxed
/image?id=1181671&width=400&download=1 → saves as a file

Dimensions are clamped to 16–6000px. Requests for a specific id are immutable and cached for a year, so they are effectively free after the first hit.

Crop & focal point

When both sides are pinned, the photo is cropped to fill that box — and by default the crop is centred, which can cut the subject in half. fp-x and fp-y move the anchor, as a fraction of each axis.

/image?id=1181671&width=1200&height=630              → centred crop
/image?id=1181671&width=1200&height=630&fp-y=0.25    → anchored nearer the top
/image?id=1181671&width=1080&height=1920&fp-x=0.7    → anchored right of centre

Rather than guessing the numbers, open any photo and drag the crop box — the URL updates as you go, and you can copy it straight out.

Format & effects

Encoding, quality and a couple of visual effects are applied by the same CDN that does the resizing, so they cost nothing extra.

/image?id=1181671&width=800&format=webp       → WebP, usually 25–50% smaller
/image?id=1181671&width=800&format=avif&q=60 → AVIF at a lower quality
/image?id=1181671&width=800&dpr=2            → 1600px of pixels in an 800px box
/image?id=1181671&width=800&blur=40          → blurred, for background art
/image?id=1181671&width=800&grayscale=1      → no colour

Building a whole layout? The placeholder generator produces every size you need in one paste.

Random images

Drop the id and ask for a random photo instead — ideal for mockups where you want real photography rather than grey boxes.

<!-- any curated photo, 600×400 -->
<img src="/image?random=1&width=600&height=400" alt="" />

<!-- narrowed to a subject -->
<img src="/image?random=1&query=mountains&width=1200&height=630" alt="" />

Random responses are sent with no-store, so each request genuinely returns a different photo.

JSON endpoints

The same data powering this site is available as JSON if you would rather build your own gallery.

GET /api/photos?query=nature&page=1&per_page=24
GET /api/photos?orientation=landscape&color=blue
GET /api/photos/1181671
GET /api/collections/{collectionId}?page=1

List endpoints return { photos, page, perPage, totalResults, nextPage }. When nextPage is null, you have reached the end.

Notes & limits

Photos come from Pexels and are free for personal and commercial use under the Pexels licence.
Upstream rate limits apply. If a page shows a warning banner, that is Pexels throttling — wait a minute and retry.
This is a hobby project, not a CDN. Use it for prototypes, demos and mockups rather than high-traffic production pages.

Start browsing photos