Image Placeholder API: The Complete Guide

Need placeholder images for your mockups or development? This guide covers everything you need to know about generating placeholder images via API, including custom dimensions, colors, text overlays, and implementation examples.

What are Placeholder Images?

Placeholder images are temporary images used during development, design mockups, or when actual content isn't available yet. They help visualize layouts, test responsive designs, and demonstrate image placement without requiring real assets.

A placeholder image URL like https://api.tinyfn.io/v1/placeholder/800x600 generates an 800x600 pixel image on the fly.

Why Use a Placeholder API?

Using an API for placeholder images offers several advantages:

• Dynamic Sizing: Generate any dimension on demand
• No Storage: No need to store placeholder files
• Customizable: Change colors, text, and formats via URL
• Fast Development: Speed up mockup and prototype creation

Using the Placeholder API

TinyFn provides a simple URL-based endpoint to generate placeholders:

GET https://api.tinyfn.io/v1/placeholder/800x600
GET https://api.tinyfn.io/v1/placeholder/800x600?bg=007bff&text=ffffff&label=Product+Image

Content-Type: image/png
[Binary image data - 800x600 placeholder image]

Parameters

Code Examples

HTML

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

<!-- Custom colors and text -->
<img src="https://api.tinyfn.io/v1/placeholder/800x400?bg=007bff&text=fff&label=Hero+Banner" alt="Hero">

<!-- WebP format -->
<img src="https://api.tinyfn.io/v1/placeholder/300x300?format=webp" alt="Square">

JavaScript / React

// Generate placeholder URL dynamically
function getPlaceholder(width, height, options = {}) {
  const { bg = 'cccccc', text = '969696', label } = options;
  let url = `https://api.tinyfn.io/v1/placeholder/${width}x${height}`;
  const params = new URLSearchParams();
  if (bg !== 'cccccc') params.set('bg', bg);
  if (text !== '969696') params.set('text', text);
  if (label) params.set('label', label);
  return params.toString() ? `${url}?${params}` : url;
}

// Usage
const heroImage = getPlaceholder(1200, 600, { label: 'Hero Image' });

CSS Background

.hero-section {
  background-image: url('https://api.tinyfn.io/v1/placeholder/1920x1080?bg=333&text=666');
  background-size: cover;
  background-position: center;
}

Customization Options

• Dimensions: Any width and height from 1x1 to 4000x4000
• Colors: Custom background and text colors using hex codes
• Labels: Custom text labels or automatic dimension display
• Formats: PNG, JPG, GIF, or WebP output formats
• Retina: Double dimensions for @2x displays

Best Practices

1. Use dimension labels: Makes it easy to identify required sizes
2. Match aspect ratios: Use the same aspect ratio as your final images
3. Test responsiveness: Generate various sizes to test responsive layouts
4. Replace before production: Always replace placeholders with real images