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 -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.
Standard fallback
/api/v1/640x360 Dimensions only. SVG output with default brand styling.
Custom color and label
/api/v1/800x450/18181B/FFFFFF?text=Product+Image Brand-safe colors and readable fallback copy from the URL.
Avatar initials
/api/v1/avatar/160?text=JD Compact circular avatars for users, teams, and organizations.
Square product tile
/api/v1/square/400?text=Product Equal width and height for ecommerce grids and card layouts.
Hero banner
/api/v1/banner/1200x400?text=Docs+Preview Wide banners for docs, landing pages, and marketing previews.
Blog thumbnail
/api/v1/thumbnail/1200x630?text=How+to+Fix+Broken+Images&style=soft&label=Guide Featured-image thumbnails with decorative elements outside the text safe zone.
Skeleton
/api/v1/skeleton/640x360 Reserve layout space with a neutral skeleton block.
Animated shimmer
/api/v1/animated/skeleton/640x360 Motion placeholder while upstream media or charts resolve.
Blur placeholder
/api/v1/blur/800x450 Soft blurred state for progressive image loading workflows.
Line chart placeholder
/api/v1/chart/line/800x500 Dashboard-ready chart placeholder generated from the route.
Gradient placeholder
/api/v1/gradient/800x450 Static purple-to-blue gradient for empty media, previews, and hero states.
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. |
.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.
<img
src="https://fallback.pics/api/v1/800x450/18181B/FFFFFF?text=Product+Image"
width="800"
height="450"
alt="Product image fallback"
/> <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'"
/> .product-card::before {
background-image: url("https://fallback.pics/api/v1/600x400/F4F4F5/52525B?text=Loading");
} export function fallbackImage(width, height, label) {
const params = new URLSearchParams({ text: label });
return `https://fallback.pics/api/v1/${width}x${height}?${params}`;
} 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"
/>
);
} 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
/>
);
} 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. |
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.