Image placeholder: 3 simple sizes for a safe layout

Reference

Name	Type	Required	Description
`width`	integer	no	1–2000 pixels. Default: 100.
`height`	integer	no	1–2000 pixels. Default: 100.
`color`	string	no	Hex colour, 3 or 6 digits, optional #. Empty means gradient.
`gradient`	bool	no	Force the warm gradient. Default: false.
`text`	string	no	Short centered text, maximum 100 characters.
`type`	string	no	png, jpg, jpeg, webp. Default: png.

Example request

curl -s "https://api2.globus.studio/v2/ph_image?width=640&height=360&text=GLOBUS"

Open documentation

The image placeholder endpoint returns a generated image for a layout test. You choose the width, the height and the colour, and the response is a PNG, JPEG or WebP. A placeholder at the final size shows spacing and cropping problems before the real artwork exists.

What the image placeholder endpoint returns

The body is the image itself. The content type depends on type: image/png by default, or the matching type for JPEG and WebP. A browser can use the URL directly in an img element.

HTTP/1.1 200 OK
Content-Type: image/png

<PNG binary>

Parameters

width and height are pixels, from 1 to 2000 each. color is a hex value with three or six digits, with or without the hash. gradient forces the warm gradient. text adds a short centered label of up to 100 characters, and type selects png, jpg, jpeg or webp.

Defaults keep the call short

The default is the old contract: a 100 by 100 image with a gradient, even when color is omitted. That makes a quick test possible, and it also means a missing colour does not produce a plain square. Pass the colour when the exact fill matters.

Size limits and errors

The image is capped by limits.image_pixels at 4 million pixels. A request above the cap or an invalid colour returns 400. If the GD extension is missing on the server, the endpoint returns 501. A client should read the status code before it tries to decode the body.

Caching and responsive images

The response can be cached by the browser. Add a size or a version to the URL when the design changes. A placeholder can also demonstrate srcset: generate two sizes and let the browser choose. The markup stays the same when the real image arrives.

<img src="https://api2.globus.studio/v2/ph_image?width=600&height=400"
     width="600" height="400" alt="">

Alt text

A placeholder is decorative. Use an empty alt attribute so a screen reader skips it. If the image carries meaning in a demo, write a short description instead. The same rule applies when the placeholder stands in for a chart or a product photo.

Colour and contrast

A mid-grey placeholder shows both light and dark text. A white placeholder can hide a contrast problem. Pick a colour that differs from the page background so the image bounds are visible during the review. A label in text helps a reviewer see which slot they are looking at.

An image placeholder can stand in for a social preview while the page is in review. Generate the size the network expects, then replace it with the final artwork. A grey rectangle as a permanent preview gives a shared link no context, so keep the placeholder out of the published tags.

For print, generate at the physical size and resolution you need. A 600-pixel image stretched to a poster looks soft. The endpoint caps the pixel count, so a large print piece needs a different source. A placeholder is a test tool, not a production asset.

Limits

The image placeholder returns a flat colour or the warm gradient, not a photo or an illustration. It is rate limited like the other endpoints, so do not call it for every image on a page. Generate one file for each size and keep it in the test fixture. Read the image placeholder guide for a full layout test and a review checklist.

Pair the image placeholder with the text placeholder for a complete test page. For a printed code, use the QR generator.

Further reading: W3C WAI image guidance.