Skip to main content

Placeholder Image API

MOCK DATA

Hotlinkable SVG placeholder images at any size from 8 to 4000 px — custom label, colors and an optional gradient. Deterministic and crisp at every scale.

Generated test data for fixtures and development

Base URL
/api/images
Category
Design & Media
Capabilities
1 route
Last updated
July 29, 2026

GET /api/images/placeholder Render a placeholder SVG at any size

A solid (or gradient) rectangle with a centered, auto-sized label. Defaults to a 600×400 dark canvas labeled with its own dimensions.

Live requestRuns against the public API
No key required
GET/api/images/placeholder

Request parameters

Image width in pixels (8–4000).

Image height in pixels (8–4000).

Centered label (up to 80 characters, XML-escaped). Defaults to '<width>×<height>', e.g. '600×400'.

Background color as exactly 6 hex digits without '#' (e.g. 0ea5e9). Invalid values are a 400. Default 1c1917 (dark stone).

Label color as exactly 6 hex digits without '#'. Invalid values are a 400. Default fafaf9 (off-white).

Render the background as a diagonal two-stop gradient from 'bg' to a variant hue-rotated 30° with lightness shifted 12% (visible even for grays).

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
<img src="https://randomapi.dev/api/images/placeholder" alt="Generated image" />
curl -o image.svg "https://randomapi.dev/api/images/placeholder"
const res = await fetch("https://randomapi.dev/api/images/placeholder");
const svg = await res.text();
import requests

svg = requests.get("https://randomapi.dev/api/images/placeholder").text
Parameters Route-specific request inputs 6
width int

Image width in pixels (8–4000).

default: 600
allowed: 8 – 4000
example: width=1200
height int

Image height in pixels (8–4000).

default: 400
allowed: 8 – 4000
example: height=630
text string

Centered label (up to 80 characters, XML-escaped). Defaults to '<width>×<height>', e.g. '600×400'.

allowed: ≤ 80
example: text=OG Image
bg string

Background color as exactly 6 hex digits without '#' (e.g. 0ea5e9). Invalid values are a 400. Default 1c1917 (dark stone).

default: 1c1917
example: bg=0ea5e9
fg string

Label color as exactly 6 hex digits without '#'. Invalid values are a 400. Default fafaf9 (off-white).

default: fafaf9
example: fg=f8fafc
gradient boolean

Render the background as a diagonal two-stop gradient from 'bg' to a variant hue-rotated 30° with lightness shifted 12% (visible even for grays).

default: false
example: gradient=true

Documented examples

Build-generated requests and complete responses 3
Default 600×400 placeholder
GET /api/images/placeholder
Default 600×400 placeholder
Social card: 1200×630 with label and gradient
GET /api/images/placeholder?width=1200&height=630&text=OG+Image&gradient=true
Social card: 1200×630 with label and gradient
Light theme avatar slot
GET /api/images/placeholder?width=256&height=256&bg=e7e5e4&fg=292524
Light theme avatar slot

About this API

Coverage, behavior and common use cases

Coverage & behavior

Returns an actual SVG image (Content-Type: image/svg+xml) you can drop straight into an <img src>, a CSS background, a README or an og:image tag. Because it's vector, it stays pixel-crisp at any display scale and weighs a few hundred bytes regardless of size.

Every parameter genuinely changes the picture:

  • width × height set the canvas (8–4000 px each, default 600×400) — emitted as both width/height attributes and the viewBox.
  • text (≤ 80 chars) is the centered label. When omitted it defaults to the dimensions with a real multiplication sign, e.g. 600×400. The label is XML-escaped, so markup like <script> renders as harmless literal text.
  • bg / fg are 6-digit hex colors without # (default 1c1917 on fafaf9). Anything that isn't exactly 6 hex digits — red, fff, #1c1917 — is a 400, never a silent fallback.
  • gradient=true swaps the flat background for a diagonal two-stop gradient: from bg to bg hue-rotated 30° with lightness shifted 12% toward the opposite extreme, so it stays visible even for pure grays.

The label auto-sizes: font-size = clamp(10, min(w,h)/5, 1.6·w/length), so short labels scale with the canvas and long labels shrink to fit the width. The output is fully deterministic — the same URL returns a byte-identical SVG forever and is served with long cache headers, making it safe to hotlink.

Use it for

  • Fill image slots in mockups and wireframes before real assets exist
  • Generate og:image / social-card placeholders at exactly 1200×630
  • Stable visual fixtures for tests and Storybook — the same URL renders a byte-identical SVG

Frequently asked questions

Practical answers about this endpoint 3
How do I set the size?

In the URL — width and height params — and the SVG stays crisp at any resolution.

Can I brand the placeholder?

Yes — bg and fg take hex colors, text overrides the label and gradient=true renders a two-tone background.

Why SVG instead of JPEG?

SVG is generated at the edge in microseconds, caches aggressively and stays sharp at every DPI — ideal for layout placeholders. If you need photos, this honestly isn't a photo service.

Related APIs

Useful next tools in the catalog
Avatar Placeholder API MOCK DATA

Deterministic SVG avatars from any seed string — identicons, initials and abstract shapes. Same seed, same avatar forever; plus ready-to-use avatar URL batches.
SVG Sparkline & Chart Placeholder API MOCK DATA

Sparkline SVGs straight from a URL — plot 2–100 numbers as a line, area or bar chart with custom size, color and smoothing. No chart library needed.
Random Color API MOCK DATA

Random colors in hex, RGB and HSL with hue and luminosity filters, nearest CSS color names and WCAG contrast text — plus deterministic color-scheme palettes.
Barcode Generator API REAL DATA

Real, scannable SVG barcodes — EAN-13 with automatic check digits and Code 128 set B. Custom height, optional label, deterministic and safe to hotlink.