API Reference

Base URL

https://fallback.pics/api/v1

All API endpoints are relative to this base URL.

URL Structure

Basic Format

 https://fallback.pics/api/v1/[width]x[height][.format][/bgColor][/textColor][?parameters]

Path Components

width - Image width (10-4000)
height - Image height (10-4000)
format - Optional: svg, png, jpg, webp, avif, gif
bgColor - Optional: Background color
textColor - Optional: Text color

Examples

/400x300
/400x300.png
/400x300/FF0000/FFFFFF
/400x300?text=Hello

Preset Format

 https://fallback.pics/api/v1/[preset]/[...parameters]

Available Presets

square - Square image
avatar - Circle avatar
banner - Wide banner
blur - Blurred effect
skeleton - Skeleton loader
ai - AI-powered
animated - Animated
chart - Chart mockup

Examples

/square/400
/avatar/200?text=JD
/banner/1200x400
/animated/pulse/400x300
/chart/bar/600x400

Query Parameters

Parameter	Type	Description	Example
`bg` or `bgColor`	string	Background color (hex or CSS name)	`?bg=FF0000`
`fg` or `textColor`	string	Text/foreground color	`?fg=FFFFFF`
`text` or `label`	string	Custom text (use + for spaces, \n for newlines)	`?text=Hello+World`
`font`	string	Font family name	`?font=roboto`
`fontSize`	number	Font size in pixels	`?fontSize=24`
`retina`	number	Retina multiplier (2 or 3)	`?retina=2`
`context`	string	AI context (with /ai preset)	`?context=tech`
`mood`	string	AI mood (with /ai preset)	`?mood=minimal`
`reducedMotion`	boolean	Disable animations	`?reducedMotion=true`

Response Headers

Content-Type

Varies based on format:

image/svg+xml - SVG format
image/png - PNG format
image/jpeg - JPEG format
image/webp - WebP format
image/avif - AVIF format
image/gif - GIF format

Cache-Control

public, max-age=31536000, immutable

Images are cached for 1 year

Access-Control-Allow-Origin

*

CORS enabled for all origins

Code Examples

HTML

<!-- Basic placeholder -->
<img src="https://fallback.pics/api/v1/400x300" alt="Placeholder">

<!-- Custom colors and text -->
<img src="https://fallback.pics/api/v1/600x400/3B82F6/FFFFFF?text=Product+Image" alt="Product">

<!-- Avatar with initials -->
<img src="https://fallback.pics/api/v1/avatar/100?text=JD" alt="User Avatar">

<!-- Animated loading state -->
<img src="https://fallback.pics/api/v1/animated/pulse/200x200" alt="Loading">

<!-- Chart mockup -->
<img src="https://fallback.pics/api/v1/chart/bar/600x400" alt="Sales Chart">

CSS

/* Background image placeholder */
.hero {
  background-image: url('https://fallback.pics/api/v1/1920x1080/gradient');
  background-size: cover;
}

/* Loading state background */
.loading {
  background-image: url('https://fallback.pics/api/v1/animated/skeleton/400x300');
}

/* Avatar fallback */
.avatar {
  background-image: url('https://fallback.pics/api/v1/avatar/200?text=USER');
}

JavaScript

// Generate placeholder URL
function getPlaceholder(width, height, options = {}) {
  const baseUrl = 'https://fallback.pics/api/v1';
  let url = `${baseUrl}/${width}x${height}`;
  
  if (options.format) {
    url += `.${options.format}`;
  }
  
  const params = new URLSearchParams();
  if (options.bg) params.append('bg', options.bg);
  if (options.fg) params.append('fg', options.fg);
  if (options.text) params.append('text', options.text);
  if (options.font) params.append('font', options.font);
  
  const queryString = params.toString();
  if (queryString) {
    url += `?${queryString}`;
  }
  
  return url;
}

// Usage
const placeholder = getPlaceholder(400, 300, {
  bg: 'navy',
  fg: 'white',
  text: 'Loading...',
  font: 'inter'
});

// Set image source
document.getElementById('myImage').src = placeholder;

React

import React from 'react';

const PlaceholderImage = ({ 
  width = 400, 
  height = 300, 
  text, 
  bg = '7C3AED', 
  fg = 'FFFFFF',
  className 
}) => {
  const baseUrl = 'https://fallback.pics/api/v1';
  const params = new URLSearchParams();
  
  if (text) params.append('text', text);
  if (bg !== '7C3AED') params.append('bg', bg);
  if (fg !== 'FFFFFF') params.append('fg', fg);
  
  const queryString = params.toString();
  const src = `${baseUrl}/${width}x${height}${queryString ? `?${queryString}` : ''}`;
  
  return (
    <img 
      src={src} 
      alt={text || `${width}x${height} placeholder`}
      className={className}
      width={width}
      height={height}
    />
  );
};

// Usage
<PlaceholderImage 
  width={600} 
  height={400} 
  text="Product Image"
  bg="3B82F6"
  className="rounded-lg shadow-md"
/>

Error Responses

400 Bad Request

Invalid parameters provided

• Dimensions outside 10-4000 range
• Invalid color format
• Malformed URL structure

Example Error

Error: Invalid dimensions (10-4000 allowed)

Rate Limits & Usage

No Rate Limits!

Fallback.pics currently has no rate limits. All features are free to use without authentication.

Unlimited requests
No authentication required
All features available