Skip to content

Documentation

Everything is a URL. No account, no key, and every parameter is optional.

URL anatomy

https://placehold.xerobi.com/{width}x{height}[@2x]/{background}/{text-colour}.{format}?text=…&font=…

The size is the only required part. Height defaults to the width, so /300 is a 300 × 300 square. Sizes run from 10 to 4,000 px.

Formats

SVG is the default. Add .png, .jpg, .gif, .webp or .avif to the end of the path, or use it as its own segment (/600x400/png). Add @2x, @3x or @4x to the size for sharper raster images.

Raster images are capped at 17 megapixels including the pixel ratio, and GIFs at 4. SVG has no such limit.

Colours

Give the background and then the text colour as hex (0075de, fff, 0075de80 with alpha), a CSS colour name (tomato), or transparent. Give only a background and the text colour is chosen for contrast.

/600x400/0075de/ffffff/600x400/tomato/white.png/600x400/transparent/0075de.png/600x400/0b3d91

Query parameters

text
?text=Hello+World
Label. Use + for spaces and \n for new lines. Defaults to the dimensions.
font
?font=poppins
One of the fonts listed below. Default: lato.
weight
?weight=500
100–900, snapped to what the font offers. Default: 700.
italic
?italic=1
Italic style, for fonts that have one.
size
?size=48
Font size in px. By default text is fitted to the image.
align / valign
?align=left&valign=top
left, center, right · top, middle, bottom.
transform
?transform=uppercase
uppercase, lowercase or capitalize.
lh
?lh=1.4
Line height multiplier, 0.8–3.
gradient
?gradient=ff7e5f,feb47b
2–5 colours, comma separated. Add angle (degrees, default 135).
pattern
?pattern=grid&ps=24
grid, dots, stripes or checker, with a tile size in px.
radius
?radius=24
Rounded corners, in px.
border / bc
?border=4&bc=0075de
Border width and colour (defaults to the text colour).
cross
?cross=1
Wireframe diagonals.
quality
?quality=80
1–100 for JPEG, WebP and AVIF.
embed
?embed=0
SVG only: skip embedding the font (smaller file, system font).
download
?download=1&filename=hero
Sends a Content-Disposition header so browsers save the file.

Fonts

Fonts are loaded on demand and cut down to just the glyphs your text uses, so even SVGs carry the right typeface when used in an <img> tag.

  • Lato samplelato
  • Lora samplelora
  • Montserrat samplemontserrat
  • Noto Sans samplenoto-sans
  • Open Sans sampleopen-sans
  • Oswald sampleoswald
  • Playfair Display sampleplayfair-display
  • Poppins samplepoppins
  • PT Sans samplept-sans
  • Raleway sampleraleway
  • Roboto sampleroboto
  • Source Sans Pro samplesource-sans-pro
  • Inter sampleinter
  • DM Sans sampledm-sans
  • Space Grotesk samplespace-grotesk
  • Merriweather samplemerriweather
  • Roboto Mono sampleroboto-mono

Video placeholders

Open the playground, switch to Video, and generate an MP4 or WebM from the same design as the still image: size, colours, gradient, pattern, text and font. Choose 1–30 seconds, 15–60 fps and an animation (progress bar, timecode, pulse or shimmer), with an optional play button.

Frames are drawn on an OffscreenCanvas, encoded with WebCodecs and muxed with Mediabunny inside a Web Worker in your browser, so nothing is uploaded. Those APIs are not available on the edge server, so there is no /600x400.mp4 URL; requesting one returns a 501 error. Video is limited to 3840 × 2160 pixels and 1,800 frames, and transparent backgrounds are flattened onto white.

Errors and caching

Invalid requests return JSON ({ "error": "…" }) with a 400, 404 or 413 status; browsers get a short HTML page instead. Successful images are cached for a day in browsers and a week at the edge, and every response allows cross-origin use.