Placeholder Image API — placeholder.tools.town

Any Size

1 px to 2000 px — any dimension

Every image below is a live request to the API. Each one is a real <img src> tag.

Icon 32×32

/32x32

Thumbnail 100×100

/100x100

Avatar 256×256

/256x256

Card 400×300

/400x300

Video 640×360

/640x360

Blog 800×450

/800x450

OG 1200×630

/1200x630

Full HD 1920×1080

/1920x1080

Theming

6 built-in themes

Add ?theme= to any URL. Explicit ?fg= and ?bg= hex values override the theme.

dark ?theme=dark

light ?theme=light

gray ?theme=gray

blue ?theme=blue

green ?theme=green

red ?theme=red

Custom hex colors:

https://placeholder.tools.town/640x360?bg=%231e293b&fg=%2394a3b8

Labels

Optional text labels

Without ?text= the image shows its own dimensions. With it, the label is centred and the size appears as a subtitle.

No ?text — shows dimension

(none)

Short label

?text=Card+Title

Label + dark theme

?text=Product+Hero+Image&theme=dark

Custom fg + bg hex

?fg=%233b82f6&bg=%23eff6ff&text=Custom

Presets

8 named social & UI sizes

Fetch the full list as JSON at /v1/presets — each entry includes url and url_v1.

Open Graph

1200×630

Twitter / X large card

1200×600

Instagram square

1080×1080

Story / reel (9:16)

1080×1920

HD 16:9

1280×720

VGA 4:3

640×480

Avatar thumbnail

256×256

Full HD hero

1920×1080

Copy & Paste

Use it anywhere

<!-- Basic -->
<img src="https://placeholder.tools.town/640x360" width="640" height="360" alt="" />

<!-- Dark theme with label -->
<img src="https://placeholder.tools.town/800x450?text=Hero+Image&theme=dark" width="800" height="450" alt="" />

<!-- Square avatar -->
<img src="https://placeholder.tools.town/96?theme=blue" width="96" height="96" alt="" />

![Placeholder](https://placeholder.tools.town/640x360)
![Dark themed](https://placeholder.tools.town/800x450?theme=dark&text=Preview)
![Avatar](https://placeholder.tools.town/96?theme=blue)

// Direct hot-link — no component needed
<img src="https://placeholder.tools.town/640x360" width={640} height={360} alt="" />

// Helper for dynamic placeholders
const ph = (w: number, h: number, opts?: { text?: string; theme?: string }) => {
  const p = new URLSearchParams();
  if (opts?.text)  p.set("text", opts.text);
  if (opts?.theme) p.set("theme", opts.theme);
  const qs = p.toString();
  return `https://placeholder.tools.town/${w}x${h}${qs ? "?" + qs : ""}`;
};

<img src={ph(800, 450, { theme: "dark", text: "Hero" })} alt="" />

# Save an SVG file
curl -sS "https://placeholder.tools.town/640x360" -o placeholder.svg

# Dark theme with label
curl -sS "https://placeholder.tools.town/800x450?text=Hero&theme=dark" -o hero.svg

# Batch — 3 URLs in one request
curl -sS "https://placeholder.tools.town/v1/batch?items=400x300,200x200,96x96" | jq .

# Spec for a size (returns URLs + aspect ratio)
curl -sS "https://placeholder.tools.town/v1/spec?w=1200&h=630" | jq .

Batch

Up to 50 URLs in one request

Generate multiple placeholder URLs server-side — useful for seeding a CMS, design system, or test fixture.

Request

GET https://placeholder.tools.town/v1/batch?items=400x300,200x200,96x96

Response

{
  "count": 3,
  "items": [
    {
      "w": 400,
      "h": 300,
      "url": "https://placeholder.tools.town/400x300",
      "url_v1": "https://placeholder.tools.town/v1/400x300"
    },
    {
      "w": 200,
      "h": 200,
      "url": "https://placeholder.tools.town/200x200",
      "url_v1": "https://placeholder.tools.town/v1/200x200"
    },
    {
      "w": 96,
      "h": 96,
      "url": "https://placeholder.tools.town/96x96",
      "url_v1": "https://placeholder.tools.town/v1/96x96"
    }
  ]
}

Embed Builder

Generate your URL

Pick a preset, adjust dimensions and colors, then copy the URL or <img> tag.

Width

Height

FG color

BG color

Label (optional)

Standalone ↗

API Reference

Full endpoint list

Image endpoints

Method	Path	Description
GET	/{width}x{height}	SVG at exact dimensions
GET	/{size}	Square shorthand — /256 → 256×256
GET	/v1/{width}x{height}	Versioned alias — stable contract for integrators

Query parameters

Param	Default	Description
text	—	Centred label (max 120 chars). Without it the image shows its own dimensions.
fg	#64748b	Foreground color. Accepts #rgb, #rrggbb, or #rrggbbaa (alpha ignored).
bg	#e2e8f0	Background fill. Same hex rules.
theme	—	Shorthand: dark · light · gray · blue · green · red. Explicit fg/bg override it.

JSON & utility endpoints

Method	Path	Description
GET	/v1/spec?w=&h=	Returns svg_url, aspect_ratio, and resolved colors
GET	/v1/validate?w=&h=	Validates dimensions, text length, and hex colors
GET	/v1/batch?items=…	Up to 50 comma-separated sizes → array of URLs
GET	/v1/presets	JSON list of all 8 named presets with URLs
GET	/meta	Full machine-readable service spec
GET	/embed/	Standalone interactive builder (iframeable)
GET	/health	{"status":"ok"} — uptime monitoring