Skip to content

Placeholder API

The Placeholder API generates image placeholders with flexible layout, text, colour, and styling options. You can use it for mock-ups, previews, temporary image slots, and quick design work.

Response Format

This endpoint returns an image, not JSON. The image is generated from the query parameters in the request URL.

Authentication Methods

This endpoint is publicly accessible and does not require authentication.

Characteristics:

  • No authentication required.
  • Direct image output.
  • Supports custom text, colours, gradients, borders, shadows, and alignment.
  • Useful for layouts, demos, and placeholder assets.

Usage:

curl "https://api.tylermwise.uk/v2/placeholder?size=300x200"

Endpoint

GET /v2/placeholder

Base Request

curl "https://api.tylermwise.uk/v2/placeholder?size=300x200"

HTML Embed Example

<img src="https://api.tylermwise.uk/v2/placeholder?size=300x200" alt="Placeholder image">

Query Parameters

Size and Text

Parameter Default Description Example
size required Width x height, from 1 to 4000. 300x200, 800x600
text {width}x{height} Text to display, use | for line breaks. Hello|World
font Poppins Path to a TTF font file. /path/to/font.ttf
fontSize auto Font size from 8 to 200. 24, 48

Colour and Opacity

Parameter Default Description Example
bg 558ed5 Background colour in HEX. 558ed5, #ff0066
fg ffffff Foreground or text colour in HEX. ffffff, #000000
bgOpacity 100 Background opacity from 0 to 100. 80, 50
fgOpacity 100 Text opacity from 0 to 100. 90
borderColor ffffff Border colour in HEX. 000000, ff0066
shadowColor 000000 Shadow colour. 000000, 333333

Layout and Styling

Parameter Default Description Example
align center Horizontal alignment. center, left, right
valign middle Vertical alignment. middle, top, bottom
border 0 Border width from 0 to 50. 5, 10
shadow false Enable drop shadow. true
shadowOffset 4 Shadow offset. 2, 6
shadowBlur 6 Shadow blur. 4, 10
gradient (none) Gradient in the format startColor,endColor. 558ed5,2a5f9e
gradientAngle 45 Gradient angle from 0 to 360. 90, 180

Option Details

size

The size parameter is required. It sets the image width and height in pixels, using the format widthxheight. The allowed range is 1 to 4000 for each dimension.

text

The text parameter controls the visible label on the placeholder. The default value uses the image dimensions. Use | to split text across multiple lines.

bg and fg

Use bg to set the background colour and fg to set the text colour. Both accept hex colour values, with or without the # prefix.

font and fontSize

Use font to point to a TTF font file and fontSize to set a fixed size. If you do not set fontSize, the API can choose a suitable size automatically.

align and valign

Use align to position the text horizontally and valign to position it vertically. These are useful when you want left-aligned text, centred text, or a more logo-like layout.

bgOpacity and fgOpacity

These options control transparency. Lower values make the background or text more transparent.

border and borderColor

Use border to add a border around the image. Set borderColor to control the border colour.

shadow, shadowColor, shadowOffset, and shadowBlur

Enable shadow to add a drop shadow. Use the remaining shadow options to tune its colour, position, and softness.

gradient and gradientAngle

Use gradient to create a two-colour gradient background. The gradientAngle option controls the direction of the gradient.

Example Requests

Basic placeholder

curl "https://api.tylermwise.uk/v2/placeholder?size=300x200"

Custom text and colours

curl "https://api.tylermwise.uk/v2/placeholder?size=400x300&text=Hello+World&bg=ff0066&fg=ffffff"

Multi-line text

curl "https://api.tylermwise.uk/v2/placeholder?size=500x400&text=Line+One%7CLine+Two%7CLine+Three&align=center&valign=middle"

Gradient background

curl "https://api.tylermwise.uk/v2/placeholder?size=600x400&text=Gradient&gradient=558ed5,2a5f9e&fg=ffffff"

Logo-style placeholder

curl "https://api.tylermwise.uk/v2/placeholder?size=400x400&text=My+Logo&bg=1a1a2e&fg=ffffff&border=8&borderColor=ff0066&shadow=true&shadowColor=000000"

Left-aligned dark mode

curl "https://api.tylermwise.uk/v2/placeholder?size=800x200&text=Left+Aligned&align=left&valign=middle&bg=111111&fg=eeeeee&border=2"

Gradient with border

curl "https://api.tylermwise.uk/v2/placeholder?size=500x300&text=Styled&gradient=ff66cc,6633ff&gradientAngle=90&fg=ffffff&border=5&borderColor=ffffff"

Emoji support

curl "https://api.tylermwise.uk/v2/placeholder?size=400x300&text=😀+Hello+🎉&bg=558ed5&fg=ffffff"

Multi-line emoji

curl "https://api.tylermwise.uk/v2/placeholder?size=500x300&text=😀%7C🎉+Hello%7C🚀&align=center&valign=middle&bg=2a2a4e&fg=ffffff"

Notes

  • The size parameter is required.
  • Use | to create line breaks in the text parameter.
  • The API supports emoji and other special characters in text.
  • Gradient and solid colour settings can be combined.
  • Borders, shadows, and alignment options help you create more polished placeholders.
  • You can use the endpoint directly in an <img> tag.

HTTP Status Codes

Standard responses may include:

  • 200 - Success.
  • 400 - Bad Request.
  • 429 - Too Many Requests.
  • 500 - Internal Server Error.

Versioning

This page documents version 2 of the Placeholder API, available under the /v2/ path.