Placeholder image API reference

Generate fallback images from predictable URLs.

The fallback.pics placeholder image API turns dimensions, colors, labels, and presets into cacheable image responses for product grids, avatars, docs, loading states, and broken-image recovery. No SDK, API key, or account is required for public routes.

Base URL https://fallback.pics/api/v1

All examples below use this canonical prefix.

Quick start

Make your first request in seconds.

Paste a URL into any surface that accepts an image source, or verify the response with curl. The worker returns an image body with cache-friendly headers.

curl bash
curl -I "https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image"

URL patterns

One base URL, many image states.

Every public route starts with /api/v1. Path segments define dimensions, preset type, and optional colors. Query parameters add labels, thumbnail options, and pattern context.

Pattern Example Use case
/api/v1/{width}x{height} /api/v1/800x450 Standard SVG placeholder with default brand colors.
/api/v1/{width}x{height}/{bg}/{fg} /api/v1/800x450/18181B/FFFFFF Custom background and text colors as path segments (hex without #).
/api/v1/{width}x{height}?text={label} /api/v1/640x360?text=Product+Image Visible fallback copy for product cards and missing media states.
/api/v1/{width}x{height}.{format} /api/v1/1200x630.jpg Raster output when a client requires PNG, JPEG, or WebP.
/api/v1/avatar/{size}?text={initials} /api/v1/avatar/128?text=JD Circular initials for profiles, teams, and workspace avatars.
/api/v1/square/{size}?text={label} /api/v1/square/400?text=Tile Square placeholders for grids, tiles, and catalog cards.
/api/v1/banner/{width}x{height} /api/v1/banner/1200x400?text=Hero+Banner Wide hero, docs, and marketing banner surfaces.
/api/v1/thumbnail/{width}x{height} /api/v1/thumbnail/1200x630?text=Article+Title&style=soft&label=Guide Blog and docs featured images with a text safe zone.
/api/v1/skeleton/{width}x{height} /api/v1/skeleton/640x360 Static skeleton placeholder while async media loads.
/api/v1/blur/{width}x{height} /api/v1/blur/800x450 Blurred placeholder for progressive or LQIP-style states.
/api/v1/animated/{type}/{width}x{height} /api/v1/animated/skeleton/640x360 Animated loading states: skeleton, pulse, wave, shimmer, gradient, dots.
/api/v1/chart/{type}/{width}x{height} /api/v1/chart/line/800x500 Deterministic chart placeholders: bar, line, area, pie, donut, scatter, radar, heatmap.
/api/v1/gradient/{width}x{height} /api/v1/gradient/800x450 Static brand gradient placeholder for hero, card, and media surfaces.
/api/v1/ai/{width}x{height} /api/v1/ai/800x450?context=saas&mood=minimal Deterministic pattern backgrounds with optional context and mood.

Route examples

Live previews for common production surfaces.

Each card links to a working response. Open one in a new tab, then copy the path into your app, CMS field, or design system fixture.

Parameters

Small surface area, explicit behavior.

Name Type Description
width path number Image width in pixels. Supported range is 10–4000 on public routes.
height path number Image height in pixels. Omitted for square and avatar presets, which derive height from width.
bg / bgColor path or query hex Background color without the # prefix. Path segments override defaults; query params can override path values.
fg / textColor path or query hex Foreground or label color without the # prefix.
text query string URL-encoded label rendered inside the generated image when the preset supports text.
style query string Thumbnail background style: soft, rings, lines, or pattern.
theme query string Thumbnail palette: purple, blue, green, orange, or dark.
label query string Short category pill on thumbnail routes, such as Guide, Blog Post, or Tutorial.
accent query hex Optional thumbnail accent color without the # prefix.
color query hex Optional thumbnail text color override without the # prefix.
seed query string Optional deterministic seed for thumbnail decorative variation.
context query string Optional semantic hint for /ai pattern routes, such as ecommerce or healthcare.
mood query string Optional tone hint for /ai pattern routes, such as minimal or professional.
type path string Animation style for /animated routes: skeleton, pulse, wave, shimmer, gradient, or dots.
chart type path string Chart style for /chart routes: bar, line, area, pie, donut, scatter, radar, or heatmap.
extension path suffix Optional .svg, .png, .jpg, .jpeg, or .webp suffix. SVG is the default when omitted.
Format note: Routes without a suffix return SVG. Add .png, .jpg, .jpeg, or .webp to receive raster output encoded by the Cloudflare Images binding.

Code examples

Use the API anywhere an image URL is accepted.

HTML html
<img
  src="https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image"
  width="800"
  height="450"
  alt="Product image fallback"
/>
Broken image fallback html
<img
  src="/catalog/product-4821.jpg"
  width="640"
  height="640"
  alt="Product image"
  onerror="this.onerror=null;this.src='https://fallback.pics/api/v1/640x640?text=Product+Image'"
/>
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"
    />
  );
}
Next.js tsx
import Image from "next/image";

export function ProductPlaceholder() {
  return (
    <Image
      src="https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image"
      width={800}
      height={450}
      alt="Product image fallback"
      unoptimized
    />
  );
}
Blog thumbnail tsx
export function BlogFeaturedImage() {
  const src = "https://fallback.pics/api/v1/thumbnail/1200x630?text=How+to+Fix+Broken+Images&style=soft&theme=purple&label=Guide";

  return <img src={src} width={1200} height={630} alt="Blog featured image" />;
}

Headers

Optimized for repeated production delivery.

Content-Type

image/svg+xml, image/png, image/jpeg, or image/webp

The response MIME type matches the requested output suffix. Routes without a suffix return SVG.

Cache-Control

public, max-age=31536000, immutable

Deterministic URLs are designed for long-lived CDN caching.

CDN-Cache-Control

max-age=31536000

Cloudflare can cache deterministic image responses close to users.

Access-Control-Allow-Origin

*

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

X-Content-Type-Options

nosniff

The worker declares image content explicitly for generated image responses.

Errors

Invalid API requests return API errors, not web pages.

Request Response Detail
POST /api/v1/400x300 405 Method not allowed The public image API is read-only and supports GET plus OPTIONS preflight.
GET /api/v1/not-a-size 400 Invalid dimensions format Unknown API image paths return an API error, not homepage HTML.
GET /api/v1/0x300 400 Invalid dimensions Dimensions must be between 10 and 4000 pixels.
GET /api/v1/5000x5000 400 Invalid dimensions Oversized requests are rejected instead of generating an unbounded asset.
Privacy note: Image delivery does not require cookies, authentication, or a client SDK. Avoid placing secrets, tokens, or regulated customer data in URL text parameters because URLs may appear in logs.

Usage limits

Bounded inputs for predictable edge rendering.

Dimensions

10px–4000px

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

Output

SVG, PNG, JPEG, WebP

The default response is SVG. Raster suffixes return the matching image MIME type for clients that require bitmap assets.

Cache policy

immutable

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

FAQ

Common API questions.

Do I need an API key?

No. Public /api/v1 routes are unauthenticated. Paste the URL into an img tag, CSS background, email template, or server response.

What is the canonical base URL?

Use https://fallback.pics/api/v1 for production-generated image URLs so caching, docs, and examples stay consistent.

When should I use SVG versus JPG or WebP?

Use SVG for crisp UI placeholders and layout-stable fallbacks. Add .jpg or .webp when a raster asset is required for social crawlers, email clients, or legacy surfaces.

Can I use fallback.pics for broken image recovery?

Yes. Point onerror handlers or framework fallbacks to a deterministic /api/v1 URL that matches the slot dimensions and user-facing label.

Ready to ship image fallbacks?

Start with public /api/v1 routes, then standardize dimensions and labels across product, docs, and tests. Enterprise custom domains and SLA terms are available separately.