API Reference | fallback.pics

Standard fallback

/640x360

Create a deterministic SVG placeholder from dimensions alone.

Custom color and label

/800x450/18181B/FFFFFF?text=Product+Image

Set visible fallback copy and brand-safe colors from the URL.

Avatar initials

/avatar/160?text=JD

Generate compact initials for user, team, or organization avatars.

Skeleton state

/animated/skeleton/640x360

Reserve the final image box while asynchronous media loads.

Name	Type	Description
`width`	number	Image width in pixels. Standard routes support 1-5000px in the active worker.
`height`	number	Image height in pixels. Omit for square and avatar presets.
`bgColor`	path hex	Optional background color as a path segment after dimensions, without the # prefix.
`textColor`	path hex	Optional foreground/text color as the next path segment, without the # prefix.
`text`	query string	URL-encoded label rendered inside the generated SVG.
`extension`	path suffix	Optional route suffix such as .png or .webp. The current worker still returns SVG output.

Format note: The current edge implementation returns SVG responses. File extensions are parsed for route compatibility, but PNG, JPEG, WebP, AVIF, and GIF conversion should not be advertised until conversion is implemented in the worker.

HTML html

<img
  src="https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image"
  width="800"
  height="450"
  alt="Product image fallback"
/>

CSS css

.product-card::before {
  background-image: url("https://fallback.pics/api/v1/600x400/F4F4F5/52525B?text=Loading");
}

JavaScript ts

export function fallbackImage(width, height, label) {
  const params = new URLSearchParams({ text: label });
  return "https://fallback.pics/api/v1/" + width + "x" + height + "?" + params;
}

React tsx

export function ProductImageFallback() {
  return (
    <img
      src="https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image"
      width={800}
      height={450}
      alt="Product image fallback"
    />
  );
}

Content-Type

image/svg+xml

The production worker currently returns SVG for generated images.

Cache-Control

public, max-age=31536000, immutable

Deterministic URLs are designed for long-lived CDN caching.

Access-Control-Allow-Origin

*

Generated fallbacks can be used from browser, server, email, and native surfaces.

Dimensions

1px-5000px

Requests outside the supported range return a 400 response instead of generating an oversized asset.

Output

image/svg+xml

The worker parses common image extensions for URL compatibility, while SVG remains the active response format.

Cache policy

immutable

Deterministic URLs are safe for long-lived CDN and browser caching across repeated product states.

Ready to ship image fallbacks?

Start with public URL routes. Higher-volume usage, custom domains, and SLA terms can be handled through an enterprise agreement.

Read the Docs

Fallback images generated from predictable URLs.

Purpose-built endpoints for common image states.