Placeholder Image API: Complete URL Syntax Guide for Developers
A practical URL syntax guide for using fallback.pics as a placeholder image API, with examples for dimensions, colors, text, avatars, and skeleton states.
Placeholder image APIs give developers a fast way to reserve image space, test layouts, and handle missing media without sourcing final assets first.
fallback.pics uses a simple /api/v1 route so you can generate deterministic SVG placeholders, avatars, banners, and skeleton states from copy-paste URLs.
Foundation
What is a placeholder image API?
A placeholder image API generates images on demand from URL parameters. Developers use these URLs in product cards, avatar slots, docs, mockups, test fixtures, CMS previews, and fallback states where the final image is missing or not ready yet.
The important difference for production work is predictability. A stable URL can reserve the right layout space, keep visual states consistent, and avoid showing the browser broken-image icon when upstream media fails.
Why fallback.pics
Why use fallback.pics?
fallback.pics is built for developers who need more than a temporary mockup image. It provides readable URLs for dimensions, colors, text labels, avatars, and skeleton states while keeping the output deterministic and easy to cache.
Alternatives like placehold.co, dummyimage.com, and placeholderimage.dev are useful in the broader placeholder category. fallback.pics is positioned around production fallback states: missing product photos, empty avatar slots, documentation examples, and UI surfaces that should never collapse when media is unavailable.
Simple URL API
Use one image URL anywhere an img src, CSS background, Markdown image, or CMS media URL is accepted.
Production states
Use placeholders for mockups and fallback images for real missing or failed media.
Deterministic output
Stable URLs are easier to cache, test, log, and reuse across repeated UI surfaces.
Syntax
Basic URL syntax
The canonical fallback.pics image route starts with /api/v1. The most common format is a single dimensions segment using width x height.
Use this pattern when you need a fixed-size placeholder for a card, banner, preview, or product image slot.
https://fallback.pics/api/v1/300x200
<img
src="https://fallback.pics/api/v1/300x200"
width="300"
height="200"
alt="Placeholder image"
/>Dimensions
Set dimensions
Dimensions are specified directly in the URL as width x height. Match these values to the final image surface so your layout remains stable before the real image is available.
For responsive layouts, combine a correctly dimensioned placeholder URL with CSS aspect-ratio or explicit width and height attributes.
https://fallback.pics/api/v1/600x400
https://fallback.pics/api/v1/1200x400
https://fallback.pics/api/v1/1920x1080Colors
Set background and text colors
You can add background and text colors after the dimensions. Use hex values without the # character so the URL stays clean and copy-paste friendly.
This is useful when placeholders need to match a brand palette, dark UI, documentation theme, or product-card style.
https://fallback.pics/api/v1/600x400/18181B/FFFFFF
https://fallback.pics/api/v1/600x400/7C3AED/FFFFFF
https://fallback.pics/api/v1/600x400/F3F4F6/18181BText
Add custom text
Add readable text with the text query parameter. Keep labels generic and safe because URLs can appear in logs, analytics tools, browser history, and support screenshots.
Good placeholder labels describe the media state without exposing private data.
https://fallback.pics/api/v1/600x400?text=Product+Image
https://fallback.pics/api/v1/1200x400/18181B/FFFFFF?text=Hero+Banner
https://fallback.pics/api/v1/400x300?text=Image+UnavailableAvatars
Generate avatar placeholders
Avatar placeholders are useful for profiles, comments, team lists, account menus, and dashboards where a user has not uploaded a photo.
Use initials or short labels instead of full names when you want a safer fallback that still communicates the user slot.
https://fallback.pics/api/v1/avatar/50?text=JD
https://fallback.pics/api/v1/avatar/96?text=AP
<img
src="https://fallback.pics/api/v1/avatar/96?text=JD"
width="96"
height="96"
alt="User avatar placeholder"
/>Loading states
Generate skeleton placeholders
Skeleton placeholders are better for temporary loading states, while static fallback images are better when media is missing or has failed permanently.
Use skeleton URLs for loading cards, previews, and image frames where you want the interface to communicate that content is still on the way.
https://fallback.pics/api/v1/animated/skeleton/600x400
https://fallback.pics/api/v1/animated/skeleton/1200x400Safety
Use production-safe URL values
Do not place secrets, tokens, email addresses, order IDs, regulated data, or customer-specific private values in placeholder URL text. Treat URL text as public metadata.
For repeated UI states, prefer stable labels like Product Image, Image Unavailable, User, Preview, or Report Thumbnail.
Reference
Where to go next
Use this syntax guide as a quick reference, then move to the main API and docs pages when you need implementation details for production components.
Start with the placeholder image API page for route examples, then use the framework guides for HTML, React, and Next.js fallback behavior.
API landing page: https://fallback.pics/placeholder-image-api/
Docs: https://fallback.pics/docs/
React guide: https://fallback.pics/guides/react-image-fallback/
Next.js guide: https://fallback.pics/guides/nextjs-image-fallback/Key takeaways
What to standardize before shipping
- Use the canonical /api/v1 route for every generated fallback.pics image URL.
- Specify dimensions as width x height to keep layouts stable.
- Use hex colors without # when customizing placeholder background and text colors.
- Add custom labels with the text query parameter, but keep URL text public and generic.
- Use avatar placeholders for missing profile photos and skeleton placeholders for loading states.
Production fallback layer
Use fallback.pics anywhere an image URL is accepted.
Start with one deterministic URL and standardize fallback behavior across your design system.
Continue reading
Related articles
Complete Guide to Image Placeholders in Web Development
Learn how image placeholders protect perceived performance, preserve layout, and keep product interfaces professional when media is missing or delayed.
Image Loading Best Practices for Better UX
Practical image loading patterns for faster perceived performance, lower layout shift, and cleaner fallback states in production interfaces.