Placeholder Image API Documentation

Paste a fallback.pics URL anywhere an image source is accepted. Verify the response with curl, then copy the same URL into your app or CMS.

curl bash

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

HTML image tag html

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

Try a live image /api/v1/800x450?text=Hello Build a custom URL Interactive generator with all presets Full API reference Routes, headers, limits, and errors

Blog thumbnail

/api/v1/thumbnail/1200x630?text=How+to+Fix+Broken+Images&label=Guide

Featured-image style thumbnail with safe-zone background decoration.

Product fallback

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

Brand-safe colors and readable copy for catalog or card layouts.

Avatar initials

/api/v1/avatar/160?text=AP

Compact circular avatars for users, teams, and organizations.

Skeleton loader

/api/v1/animated/skeleton/640x360

Motion placeholder that preserves layout while media loads.

Chart placeholder

/api/v1/chart/line/800x500

Deterministic chart art for dashboards, reports, and app previews.

Gradient placeholder

/api/v1/gradient/800x450

Static brand gradient for image slots that need a polished fallback.

Pick a surface

Choose the image slot you need to stabilize: product card, avatar, docs thumbnail, loading state, or broken-image recovery.

Build the URL

Start with /api/v1, add dimensions or a preset route, then optional colors, labels, and thumbnail options.

Ship the fallback

Paste the URL into HTML, React, Next.js, CSS, CMS fields, or onerror handlers. Responses cache at the edge.

Path segments define dimensions, preset type, and optional colors. Query parameters add labels and thumbnail options. Deterministic URLs are safe to cache for repeated UI states.

Standard route text

https://fallback.pics/api/v1/[width]x[height]/[bgColor]/[textColor]?text=[label]

Blog thumbnail route text

https://fallback.pics/api/v1/thumbnail/1200x630?text=[post-title]&style=soft&theme=purple&label=Guide

Pattern	Example	When to use
`/api/v1/{width}x{height}`	`/api/v1/640x360`	Default SVG placeholder
`/api/v1/{width}x{height}/{bg}/{fg}?text={label}`	`/api/v1/800x450/18181B/FFFFFF?text=Product+Image`	Branded fallback copy
`/api/v1/avatar/{size}?text={initials}`	`/api/v1/avatar/128?text=JD`	Profile and team avatars
`/api/v1/thumbnail/{w}x{h}?text=...&label=...`	`/api/v1/thumbnail/1200x630?text=Article+Title&label=Guide`	Blog and OG thumbnails
`/api/v1/animated/{type}/{w}x{h}`	`/api/v1/animated/skeleton/640x360`	Loading animations
`/api/v1/chart/{type}/{w}x{h}`	`/api/v1/chart/bar/800x500`	Dashboard chart placeholders
`/api/v1/gradient/{w}x{h}`	`/api/v1/gradient/800x450`	Static brand gradients

Production tip: Match fallback dimensions to the final image slot and keep labels user-facing. Avoid putting secrets or regulated data in URL parameters.

Parameter	Type	Description
`width`	path number	Image width in pixels. Public routes support 10–4000px.
`height`	path number	Image height in pixels. Avatar and square presets derive height from width.
`bg / bgColor`	path or query hex	Background color without the # prefix.
`fg / textColor`	path or query hex	Foreground or label color without the # prefix.
`text`	query string	URL-encoded label shown inside supported presets.
`style`	query string	Thumbnail decoration: 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 or Blog Post.
`type`	path string	Animation or chart variant, depending on route.
`extension`	path suffix	Optional .svg, .png, .jpg, .jpeg, or .webp for raster output.

Presets encode specialized layouts so you do not have to recreate avatar circles, thumbnail safe zones, or loader motion by hand.

standard

/api/v1/800x450?text=Product+Image

General placeholders, cards, and missing media states

thumbnail

/api/v1/thumbnail/1200x630?text=Blog+Post+Title&style=soft&label=Guide

Blog featured images, CMS fallbacks, Open Graph thumbnails

avatar

/api/v1/avatar/128?text=JD

Initials for people, teams, and organizations

square

/api/v1/square/400?text=Tile

Square catalog tiles and grid layouts

banner

/api/v1/banner/1200x400?text=Campaign

Hero banners, docs headers, and marketing previews

skeleton

/api/v1/skeleton/640x360

Static skeleton blocks that preserve dimensions

animated

/api/v1/animated/skeleton/640x360

Shimmer, pulse, wave, and other loading motion

blur

/api/v1/blur/800x450

Soft blurred placeholders before real media arrives

chart

/api/v1/chart/bar/800x500

Deterministic dashboard and report visualizations

gradient

/api/v1/gradient/800x450

Static brand gradients for media and preview slots

pattern

/api/v1/ai/800x450?context=saas&mood=minimal

Deterministic decorative backgrounds with optional context

Broken image recovery

Point onerror handlers to a deterministic fallback URL that matches slot dimensions and explains the missing state.

Broken image fallback guide →

Ecommerce catalogs

Reserve product card space with square or dimensioned placeholders while vendor media is missing or delayed.

Product image placeholder →

Docs and blogs

Generate readable featured images and OG-safe thumbnails from titles without maintaining a design asset pipeline.

Generate blog thumbnails from text →

App loading states

Use skeleton and animated routes to keep dashboards and feeds stable while async images resolve.

Skeleton placeholder guide →

Broken image fallback html

<img
  src="/media/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'"
/>

React component tsx

export function ProductFallback() {
  const src = "https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image";

  return <img src={src} width={800} height={450} alt="Product image fallback" />;
}

Next.js Image tsx

import Image from "next/image";

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

Blog featured image html

<img
  src="https://fallback.pics/api/v1/thumbnail/1200x630?text=How+to+Fix+Broken+Images&style=soft&label=Guide"
  width="1200"
  height="630"
  alt="How to Fix Broken Images featured image"
/>

Caching

Prefer deterministic URLs and immutable cache headers for repeated UI states, product grids, emails, and preview surfaces.

Privacy

Image delivery does not require cookies, authentication, or a client SDK. Text parameters appear in URLs and logs, so do not place secrets, tokens, or regulated customer data in fallback image URLs.

Errors

Invalid dimensions and unknown image paths return explicit API errors—not homepage HTML—so monitoring can distinguish bad requests from site traffic.

Enterprise

Custom domains, support windows, and SLA commitments can be handled through an enterprise deployment agreement. Contact sales.

React image fallback Next.js image fallback HTML onerror fallback URL syntax deep dive Full API reference Interactive generator

Do I need to install a package?

No. fallback.pics is URL-based. Any surface that accepts an image URL can use /api/v1 routes directly.

What should my first URL look like?

Start with https://fallback.pics/api/v1/800x450?text=Product+Image, then adjust dimensions, colors, and preset routes to match your UI.

When should I use a preset instead of width x height?

Use presets when the output shape is specialized: avatar for initials, thumbnail for blog art, skeleton for loaders, chart for report previews, gradient for branded media slots, or banner for wide hero slots.

Where is the difference between docs and API reference?

This page explains how to adopt fallback.pics in products and frameworks. The API reference lists routes, headers, limits, and error behavior in full.

Ready to standardize image fallbacks?

Start with one URL in your highest-traffic image slot, then expand into presets, team conventions, and custom domains.

Open generator View API reference

Ship reliable image fallbacks without an SDK.

Replace a missing image in one URL.