Documentation

The whole API

Two GET routes, four parameters each. No auth, no SDK.

Routes

GET /one/:w/:h/:format/:collection/:n

A specific image. The same URL always returns the same image. Cached at the edge — use this when you want the comp to look the same on every reload.

GET

https://cdn.imgipsum.com/one/800/800/webp/portraits/3

GET /random/:w/:h/:format/:collection

Picks a random image and 302 redirects to the matching /one/… URL. Different image per request; the redirect target is cached.

GET

https://cdn.imgipsum.com/random/1200/800/avif/landscapes

Rate-limited per IP. Hitting the limit returns 429; back off and retry — cached URLs still serve.

Parameters

Name	Type	Description
w	enum	Width in pixels. One of `100, 200, 400, 800, 1200, 1600`.
h	enum	Height in pixels. Same options as `w`.
format	enum	Output format. One of `webp, avif, jpeg, png`.
collection	string	Curated bucket. See collections.
n	int	`/one` only. 1-indexed image number within the collection.

Sizes are a closed enum — anything else returns 400.

Collections

Each collection is a fixed, curated set of images. Image n is stable across deploys.

portraits 20 images

Faces, expressions, character.

food 20 images

Plates, ingredients, kitchen craft.

landscapes 20 images

Vistas, weather, terrain.

architecture 20 images

Buildings, lines, structure.

pets/dogs 20 images

Good boys and girls.

pets/cats 20 images

Indifferent royalty.

pets/other 5 images

Everything else with whiskers, scales, or feathers.

Recipes

Drop-in placeholder

Plain HTML, lazy-loaded, fixed dimensions to avoid layout shift.

html

<img
  src="https://cdn.imgipsum.com/random/800/800/webp/portraits"
  alt="Random portrait"
  width="800"
  height="800"
  loading="lazy"
/>

Responsive srcset

Pin to a specific /one/… image and let the browser pick a size. All three URLs share content (same n) but at different widths.

html

<img
  src="https://cdn.imgipsum.com/one/800/800/webp/landscapes/1"
  srcset="
    https://cdn.imgipsum.com/one/400/400/webp/landscapes/1 400w,
    https://cdn.imgipsum.com/one/800/800/webp/landscapes/1 800w,
    https://cdn.imgipsum.com/one/1600/1600/webp/landscapes/1 1600w
  "
  sizes="(min-width: 1024px) 50vw, 100vw"
  alt=""
/>

Format negotiation

Use <picture> for clients that don't support AVIF/WebP. The CDN doesn't sniff Accept — you pick.

html

<picture>
  <source
    type="image/avif"
    srcset="https://cdn.imgipsum.com/one/800/800/avif/food/1"
  />
  <source
    type="image/webp"
    srcset="https://cdn.imgipsum.com/one/800/800/webp/food/1"
  />
  <img src="https://cdn.imgipsum.com/one/800/800/jpeg/food/1" alt="" />
</picture>

Programmatic fetch

/random returns a 302. Most clients (browsers, fetch) follow it automatically.

const res = await fetch(
  'https://cdn.imgipsum.com/random/1200/800/webp/architecture',
  { redirect: 'follow' }
);
const blob = await res.blob();

That's the whole API.

Back to the playground