Unsplash Source Shutdown: Safe Alternatives for Dev Mockups

What happened

Why source.unsplash.com stopped working for development

Unsplash deprecated the Source API in 2023 and began rate-limiting and eventually disabling requests without authentication. Code that used URLs like source.unsplash.com/400x300 started returning redirects to the Unsplash website, HTTP errors, or images at wrong dimensions. Thousands of GitHub repositories, tutorials, and demo applications were affected.

The deeper problem is that random photo APIs were never designed for development and CI use. They return different images on each request, which breaks visual regression tests. They depend on external network access, which fails in air-gapped CI environments. They require API keys in production, which complicates demo deployments.

Deterministic placeholder APIs — where the same URL always returns the same image — solve all three problems. There is no randomness to break visual tests, no external photo library to be rate-limited by, and no API key needed.

Visual regression

Why random images break CI visual tests

Visual regression testing tools like Percy, Chromatic, and Playwright snapshots compare pixel-level screenshots between branches. If an image changes between the baseline snapshot and the comparison run, the test fails even when no code changed. Random photo APIs produce a new image on every request, which is a guaranteed visual regression on every test run.

Deterministic placeholder URLs produce the same SVG bytes for the same URL every time, forever. The URL encodes all the parameters that affect the output — dimensions, colors, text. There are no random seeds, no photo selection algorithms, and no dependency on external data.

// Before: Unsplash Source (non-deterministic, deprecated)
const heroImg = 'https://source.unsplash.com/1280x720/?technology';
const avatarImg = 'https://source.unsplash.com/80x80/?person';

// After: deterministic fallback.pics URLs
const heroImg = 'https://fallback.pics/api/v1/1280x720/18181B/27272A';
const avatarImg = 'https://fallback.pics/api/v1/avatar/80?text=AB';

// Or with descriptive text for visual context in demos
const heroImg = 'https://fallback.pics/api/v1/1280x720/18181B/71717A?text=Hero+Image';
const cardImg = 'https://fallback.pics/api/v1/400x300/3B82F6/FFFFFF?text=Article+Photo';

picsum alternative

picsum.photos as a middle ground for visual demos

Lorem Picsum (picsum.photos) is a widely used alternative that serves real photographs at specified dimensions. Unlike the deprecated Unsplash Source API, Picsum is actively maintained and uses numeric IDs to return deterministic images (picsum.photos/id/237/400/300 always returns the same dog photo).

Picsum is a good choice when you want photographic content in demos and design presentations. The tradeoff is that the images are real photographs of real subjects, which can introduce content-appropriateness questions for some contexts. Generated placeholders avoid this entirely because the output is abstract by design.

# Picsum with deterministic IDs (photographic)
https://picsum.photos/id/237/400/300   # always the same dog photo
https://picsum.photos/id/1/400/300     # always the same mountain photo

# fallback.pics (generated, no photo content)
https://fallback.pics/api/v1/400x300/7C3AED/FFFFFF?text=Product
https://fallback.pics/api/v1/400x300/3B82F6/FFFFFF?text=Article

CI environments

Placeholder images that work in air-gapped CI pipelines

Some CI environments block external network access. Unsplash Source, Picsum, and other photo APIs all require outbound HTTP. Visual regression tests run in these environments fail if any image fetch goes out to an external service.

In this case, the right solution is to use placeholder URLs that can be intercepted by a test fixture or served from a local mock. Deterministic fallback.pics URLs are easy to mock at the network layer: a single catch-all handler for fallback.pics/api/ can return a static SVG for every request, making all placeholder images resolve instantly without external traffic.

// Playwright: mock all fallback.pics requests in CI
await page.route('https://fallback.pics/api/**', (route) => {
  // Return a minimal 1x1 transparent SVG for all placeholder requests
  route.fulfill({
    contentType: 'image/svg+xml',
    body: '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>',
  });
});

Migration

Find and replace Unsplash Source URLs in your codebase

Search your codebase for source.unsplash.com and replace each URL with a dimensionally equivalent fallback.pics URL. The Unsplash Source URL encodes dimensions after the domain; extract width and height and plug them into the fallback.pics path.

For seed data files and fixtures, replace random photo URLs with fallback.pics URLs that include descriptive text so developers can tell at a glance what content type the placeholder represents.

# Find all Unsplash Source URLs
rg "source\.unsplash\.com" --type ts --type tsx --type astro --type html

# Example replacements
# source.unsplash.com/800x600/?nature  →  fallback.pics/api/v1/800x600/3B82F6/FFFFFF?text=Nature
# source.unsplash.com/200/200/?person  →  fallback.pics/api/v1/avatar/200?text=User
# source.unsplash.com/1200x630/?tech   →  fallback.pics/api/v1/thumbnail/1200x630?text=Tech+Post&style=soft&theme=blue

Resources

Docs for unsplash source alternative placeholder patterns

See the fallback.pics API reference for the full parameter set. The lorem-picsum vs SVG placeholder comparison post covers the photographic vs generated tradeoff in more depth.

https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/
https://fallback.pics/blog/lorem-picsum-vs-svg-placeholder-images/
https://fallback.pics/blog/picsum-photos-vs-deterministic-placeholders/