JPKCom DB

Placeholder Service — Manual

Complete reference for the Placeholder Service: the public URL scheme with every parameter and limit, each interface option, and the PNG and SVG output paths.

Back to the overview: Placeholder Service · Open the tool live: www.jpkc.com/tools/ph/

This manual describes the Placeholder Service in full: the publicly callable URL scheme with every parameter and limit, each interface option, and the two output paths — PNG (server) and SVG (browser). The tool's interface is in English, so the card and button names appear here in their original spelling.

The interface at a glance

The generator page is two-column: outputs on the left (Preview, Generated Code, Direct URL, API Usage), inputs on the right (Dimensions, Colors, Text Options, Actions, SVG Output). You change something on the right and the URL and code update on the left immediately — only the image preview is reloaded deliberately, by button (see Preview and code output). The default is an 800 × 600 image with a dark background (3c4955) and light text (eeeeee) showing the dimensions "800 x 600".

The URL scheme (the real API)

The heart of the tool is a real, public URL scheme: every placeholder image can be produced just by requesting an address — no interface, no account, no file download. The server generates a PNG from it on the fly.

Structure of the address

It starts with the tool URL, followed by a parameter segment and a trailing slash:

https://www.jpkc.com/tools/ph/?WIDTHxHEIGHT-BACKGROUND-TEXTCOLOR/
https://www.jpkc.com/tools/ph/?WIDTHxHEIGHT-BACKGROUND-TEXTCOLOR-Text/

The segment consists of three or four hyphen-separated parts: first the dimensions as WIDTHxHEIGHT, then the background colour, then the text colour, and optionally a fourth part with a caption of your own. The optional query parameters (see below) go after the trailing slash, joined with &.

Required parameters

Part Meaning Format / limit
W Width Integer 1–3200
H Height Integer 1–3200
BG Background colour 6-digit hex without # (e.g. cccccc)
TXT Text colour 6-digit hex without # (e.g. 333333)
Text Custom text (optional) Letters, numbers, spaces; + = space; max. 255 characters

So dimensions and colours are always required; the text is optional. Leave the text out and the image shows its dimensions as "W x H".

Optional query parameters

Append these after the trailing slash (joined with &):

Parameter Effect
&size=small|medium|large|xlarge Fixed text size instead of automatic scaling (default: auto)
&notext=1 Hides all text — a plain colour fill
&nodim=1 Hides the dimensions line — shows only the custom text (only meaningful with a custom text set)

Example URLs

# 600 x 400, light grey, dark text, shows the dimensions
https://www.jpkc.com/tools/ph/?600x400-cccccc-333333/

# 800 x 600 in brand colours with a caption (space as +)
https://www.jpkc.com/tools/ph/?800x600-3c4955-eeeeee-Hello+World/

# force large type
https://www.jpkc.com/tools/ph/?1200x630-264653-e9c46a-Cover/&size=xlarge

# plain colour fill, no text
https://www.jpkc.com/tools/ph/?300x250-eeeeee-eeeeee/&notext=1

# only the custom text, no dimensions line
https://www.jpkc.com/tools/ph/?800x600-3c4955-eeeeee-Sale/&nodim=1

Validation and limits

The server validates every address before it generates an image:

  • The segment must have 3 or 4 parts and the first part must match WIDTHxHEIGHT exactly. Background and text colour must consist of hex digits and are checked for exactly 6 characters.
  • Dimensions must be numeric and are hard-clamped to the range 1–3200 (PH_MAX_DIMENSION). Larger or smaller values are trimmed.
  • The custom text is filtered: + becomes a space, everything except letters, digits, and spaces is removed, and the rest is cut to 255 characters (PH_MAX_TEXT_LENGTH). So umlauts, punctuation, and special characters drop out.
  • Important: if an address doesn't fit the scheme (wrong number of parts, invalid colour), the server returns no error image but shows the generator interface. A broken image URL therefore appears as a "broken image" in an <img>, because HTML comes back instead of PNG.

Dimensions

The Dimensions card has two number fields, Width and Height (1–3200 each). A Swap dimensions button (arrow icon) flips width and height — handy for switching from landscape to portrait. Below it are four presets dropdowns with ready-made sizes; clicking an entry sets width and height (see Presets).

Colors

The Colors card has two fields, Background Color and Text Color, each driven by a colour picker (hex format, with a row of predefined swatches). A Swap colors button trades the background and foreground colour — useful to quickly compare a light and a dark variant. In the URL scheme these values appear as 6-digit hex without #.

Text Options

The Text Options card controls what's printed on the image:

  • Show text on image — the master switch for text. Off → the image is a plain colour fill (equivalent to notext=1).
  • Show resolution (width × height) — shows or hides the dimensions line. This switch is only active when text is shown and a custom text is set — otherwise the image would have no text at all, which isn't allowed. Off → only the custom text appears (equivalent to nodim=1).
  • Custom Text — your own caption (max. 255 characters). Only letters, numbers, and spaces are allowed; type anything else and the field reports "Only letters, numbers, and spaces allowed" and filters it out. Leave it empty → the image shows only the dimensions.
  • Text Size — Auto (scaled to the image size), Small, Medium, Large, or Extra Large. With auto the type scales with the smaller image side; the fixed sizes correspond to 12, 24, 48, and 72 point.

When custom text and dimensions are both visible, the image renders two lines: the custom text on top, the dimensions below.

Preview and code output

Three cards on the left show the result:

  • Preview — the image preview with a badge naming the current dimensions. It does not update automatically: after each change the Update Preview button becomes active; a click reloads the image (with a cache-buster, so the browser doesn't show the old version). This saves server requests while you're still adjusting settings.
  • Generated Code — the finished <img> tag including src, alt, width, and height, with a Copy button.
  • Direct URL — the bare image URL following the scheme above, also with a Copy button.

An API Usage card summarises the URL format and parameters right inside the tool — the same details as above in this manual.

PNG and SVG download

The Actions card offers two downloads:

  • Download PNG — saves the server-generated PNG as placeholder-WxH.png. This path uses the URL scheme.
  • Download SVG — saves the browser-generated SVG variant as placeholder-WxH.svg.

SVG output in detail

The SVG Output card is a standalone, purely client-side feature — it builds an SVG graphic from your settings without a server request. At the top you get a live SVG preview, below it three tabs with a copy button:

  • SVG Source — the raw <svg> source (a <rect> as the fill, a <text> centred; with custom text plus dimensions, two <tspan> lines).
  • Data URI (CSS) — a ready-made CSS line background-image: url('data:image/svg+xml,…') to drop straight into your stylesheet.
  • IMG Tag — an <img> with an embedded SVG data URI that works without an external file and without a server request.

Because SVG is vector-based, this variant scales without quality loss. Unlike the PNG URL scheme, nothing lands on the server here — the graphic exists only in your browser until you copy or download it.

Presets: ready-made sizes

The four preset dropdowns set common sizes with one click:

  • Social Media — Facebook Post 1200 × 630, Twitter Post 1200 × 675, Instagram Square 1080 × 1080, Instagram Portrait 1080 × 1350, LinkedIn Post 1200 × 627, YouTube Thumbnail 1280 × 720.
  • Web Banners — Leaderboard 728 × 90, Large Leaderboard 970 × 90, Medium Rectangle 300 × 250, Wide Skyscraper 160 × 600, Half Page 300 × 600, Billboard 970 × 250, WP Plugin Banner 772 × 250, WP Plugin Banner @2x 1544 × 500.
  • Devices — iPhone 15 Pro 393 × 852, iPhone SE 375 × 667, iPad Pro 1024 × 1366, Desktop HD 1920 × 1080, Desktop 4K 3200 × 1800, MacBook Pro 1512 × 982.
  • Common — Square Small 150 × 150, Square Medium 300 × 300, Square Large 600 × 600, Thumbnail 150 × 100, Preview 400 × 300, Hero 1200 × 400.

Caching and operation — in brief

  • Server output format: PNG only (image/png). SVG is a browser-only feature.
  • Caching: served images carry Cache-Control: public, max-age=31536000 and an Expires one year in the future — browsers and CDNs may hold them a long time.
  • Dimensions: 1–3200 px per side, hard-clamped.
  • Text: max. 255 characters, letters/digits/spaces only; + = space.
  • Colours: 6-digit hex each, without #.
  • Error behaviour: an invalid URL → the generator interface, not an error image.

For the introduction, the audiences, and the big picture, see the overview. Hands-on walkthroughs are in the examples. You can try everything right in the tool.