API Reference
Placeholder Images
URL Pattern
https://freeplaceholder.com/{width}x{height}[.format]Path Parameters
| Part | Required | Description |
|---|---|---|
| width | Yes | Image width in pixels (1–4096) |
| height | Yes | Image height in pixels (1–4096) |
| format | No | File extension: svg, png, jpg, webp (default: svg) |
Query Parameters
All query parameters are named after Tailwind CSS utility classes.
| Parameter | Description | Example |
|---|---|---|
| bg | Background color (hex, no #) | ?bg=3b82f6 |
| gradient | Gradient direction | ?gradient=to-r |
| from | Gradient start color (hex, no #) | ?from=3b82f6 |
| via | Gradient middle color (hex, no #) | ?via=8b5cf6 |
| to | Gradient end color (hex, no #) | ?to=ec4899 |
| text-color | Text color (hex, no #) | ?text-color=ffffff |
| text | Custom text overlay | ?text=Loading... |
| text-size | Font size in pixels | ?text-size=48 |
| text-align | Text alignment (left, center, right) | ?text-align=center |
| text-transform | Text transform (uppercase, lowercase, capitalize) | ?text-transform=uppercase |
| text-decoration | Text decoration (underline, overline, line-through) | ?text-decoration=underline |
| letter-spacing | Letter spacing (Tailwind values or px) | ?letter-spacing=wide |
| font-weight | Font weight (Tailwind values) | ?font-weight=bold |
| opacity | Opacity 0–100 | ?opacity=50 |
| blur | Gaussian blur in px (0–100) | ?blur=5 |
| brightness | Brightness 0–200 (100 = normal) | ?brightness=120 |
| contrast | Contrast 0–200 (100 = normal) | ?contrast=110 |
| hue-rotate | Hue rotation 0–360 degrees | ?hue-rotate=90 |
| invert | Invert colors | ?invert=true |
| saturate | Saturation 0–200 (100 = normal) | ?saturate=150 |
| sepia | Sepia tone filter | ?sepia=true |
| grayscale | Grayscale filter | ?grayscale=true |
| border | Border width in px | ?border=2 |
| border-color | Border color (hex, no #) | ?border-color=000000 |
| border-style | Border style (solid, dashed, dotted, double, none) | ?border-style=dashed |
| rounded | Border radius (sm, md, lg, xl, 2xl, 3xl, full, or px) | ?rounded=lg |
| format | Output format (overrides extension) | ?format=png |
Examples
| URL | Description |
|---|---|
| /600x400 | 600x400 SVG with auto colors |
| /600x400.png | 600x400 PNG |
| /1920x1080.webp | Full HD WebP |
| /600x400?bg=3b82f6&text-color=ffffff | Blue bg, white text |
| /300x200?text=Banner&text-size=32 | Custom text |
Avatars
URL Pattern
https://freeplaceholder.com/avatar/{name}[.format]Parameters
| Part | Required | Description |
|---|---|---|
| name | Yes | Name to derive initials from (URL-encoded) |
| format | No | File extension: svg, png, jpg, webp (default: svg) |
Query Parameters
| Parameter | Description | Default | Example |
|---|---|---|---|
| size | Square dimensions in pixels (1–1024) | 128 | ?size=256 |
| bg | Background color (hex, no #) | Auto | ?bg=6366f1 |
| text-color | Text color (hex, no #) | Auto | ?text-color=ffffff |
| text-decoration | Text decoration (underline, overline, line-through) | none | ?text-decoration=underline |
| letter-spacing | Letter spacing (Tailwind values or px) | Auto | ?letter-spacing=wide |
| font-weight | Font weight (Tailwind values) | semibold | ?font-weight=bold |
| opacity | Opacity 0–100 | 100 | ?opacity=50 |
| blur | Gaussian blur in px (0–100) | 0 | ?blur=5 |
| brightness | Brightness 0–200 (100 = normal) | 100 | ?brightness=120 |
| contrast | Contrast 0–200 (100 = normal) | 100 | ?contrast=110 |
| hue-rotate | Hue rotation 0–360 degrees | 0 | ?hue-rotate=90 |
| invert | Invert colors | false | ?invert=true |
| saturate | Saturation 0–200 (100 = normal) | 100 | ?saturate=150 |
| sepia | Sepia tone filter | false | ?sepia=true |
| grayscale | Grayscale filter | false | ?grayscale=true |
| border | Border width in px | 0 | ?border=2 |
| border-color | Border color (hex, no #) | Auto | ?border-color=000000 |
| border-style | Border style | solid | ?border-style=dashed |
| rounded | Border radius (sm, md, lg, xl, 2xl, 3xl, full, or px) | 0 | ?rounded=lg |
| format | Output format | svg | ?format=png |
Examples
| URL | Description |
|---|---|
| /avatar/John+Doe | "JD" initials, auto colors |
| /avatar/alice.png | Single initial "A", PNG |
| /avatar/Bob?size=256&bg=ef4444&text-color=ffffff | Red, 256px |
Color Hashing
When bg and text-color are not provided, the API deterministically generates colors from the URL path using a DJB2 hash mapped to the HSL color space. The text color is automatically chosen for WCAG AA contrast compliance.
Caching
All image responses include:
Cache-Control: public, max-age=31536000, s-maxage=31536000, immutableImages are served through CloudFront CDN. Identical URLs always produce identical images, so caching is safe and permanent.
Response Codes
| Code | Meaning |
|---|---|
| 200 | Image generated successfully |
| 400 | Invalid parameters (bad dimensions, unsupported format) |
| 500 | Server error during image generation |
