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. |
| 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 fileDimensions 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.
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=1List 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.