Developer documentation

Migrate legacy placeholder URLs

Use the official local migration CLI to scan source files, review safe conversions and update verified URLs without uploading source code.

npx placeholder-photo-migrate .
npx placeholder-photo-migrate . --write
npx placeholder-photo-migrate . --check

Open the migration CLI guide

Quick start

https://placeholder.photo/800x600 creates a classic placeholder. Add colours as path segments and text as a query parameter:

https://placeholder.photo/800x600/6D5DFC/FFFFFF?text=Hello

Generator families

ClassicText, colours, borders and transparency.GradientLinear and radial multi-colour fields.PatternRepeatable developer-ready textures.AbstractDeterministic procedural art.PhotoCurated local niche imagery.LogoCoherent mock brand marks.AvatarInitials, identicons and illustrations.

Stable seeds

Use a human-readable seed whenever identity matters. The same normalized configuration, seed and renderer version returns the same asset. Curated photo selection uses immutable versioned sets: omitted set keeps the launch v1 mapping, while set=v2 opts into the expanded catalogue without reshuffling old URLs.

Caching

Deterministic requests are rendered once, stored under a content-addressed immutable cache URL and reused. Browsers and future edge layers can cache the redirect and derivative for one year. A cache hit never repeats expensive image work.

Errors and limits

Invalid image requests return a concise branded SVG error image with the correct 4xx/5xx HTTP status. Maximum width and height are 4096 pixels, total rendered pixels are bounded, DPR is limited to 3, text is bounded to five lines, and costly effects use conservative ranges.