Placeholder image API

Put a Lorem.space URL in an <img> tag and get a plain placeholder image of the size you ask for. You don't need an account or a key.

<img src="https://api.lorem.space/image?w=600&h=400" width="600" height="400" alt="">

A grey 600 by 400 placeholder image

Request

GET https://api.lorem.space/image?w={width}&h={height}&bg={hex}&fg={hex}&text={text}

Parameter	Required	What it does
`w`	No	Width in pixels, a whole number from 8 to 2000. Defaults to 500.
`h`	No	Height in pixels, a whole number from 8 to 2000. If you leave it out, the image is square.
`bg`	No	Background colour as a 3 or 6 digit hex code without `#`, such as `e2e8f0`.
`fg`	No	Text colour as a hex code without `#`.
`text`	No	Text to show, up to 60 characters. Without it, the image shows its size, such as 600×400.

The response is an SVG image with Access-Control-Allow-Origin: *. It is cached for a year, because the same URL always returns the same image. The placeholder image generator builds these URLs for you.

Older category URLs

URLs in the older format, such as https://api.lorem.space/image/game?w=150&h=220, still work and return a placeholder of the requested size. The category name appears under the size. With only w or only h, these URLs keep the old shape of the category: tall for movie, game, book and fashion, wide for car, house and furniture, and square for the rest. The hash parameter is accepted and ignored.

Errors

Status	Message	Cause
400	`invalid width size`	`w` is not a whole number from 8 to 2000.
400	`invalid height size`	`h` is not a whole number from 8 to 2000.
404	`category not found`	An older category URL uses a category that never existed.
404	`not found`	The path is not `/image`.

Errors return JSON with a message field. An invalid colour is ignored and the default colour is used.

Examples

HTML

<img src="https://api.lorem.space/image?w=300&h=250&text=Ad" width="300" height="250" alt="">

CSS background

.hero {
  background: url("https://api.lorem.space/image?w=1280&h=720&bg=1e293b&fg=f8fafc") center / cover;
}

React

{products.map(p => (
  <img key={p.id} src={`https://api.lorem.space/image?w=300&h=300&text=${encodeURIComponent(p.name)}`} alt="" />
))}

Markdown

![Placeholder](https://api.lorem.space/image?w=600&h=400)

For other ways to add a placeholder image in HTML, such as CSS boxes, inline SVG and data URIs, see the placeholder image HTML guide.

Frequently asked questions

Do I need an API key?

No. The placeholder image API has no key and no sign-up. Put the URL in an <img> tag and it works.

What image format does the API return?

It returns SVG, which browsers show in <img> tags and CSS backgrounds. For a PNG file, use the placeholder image generator.

Can I change the colours and text?

Yes. Add bg and fg with hex codes, and text with up to 60 characters.

Do old Lorem.space image URLs still work?

Yes. URLs such as /image/game?w=150&h=220 return a placeholder of the requested size with the category name on it.

Can I load the images from JavaScript on my own domain?

Yes. Every response includes Access-Control-Allow-Origin: *.