Placeholder Service — Manual

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

This manual describes the Placeholder Service (called "Placeholder Generator" in the interface) in full: the publicly callable URL scheme with every parameter and limit, the rule that decides how the text is set into the image, each interface option, and the two output paths — raster image (server) and SVG (browser). Card and button names appear exactly as the tool spells them, so you can find your way around the real interface.

The interface at a glance

The generator page has two columns: outputs on the left (Preview, HTML, Image URL, URL format), inputs on the right (Dimensions, Colors, Text, Image file with the download buttons) and, below them, the SVG output (SVG (no server needed)). Everything updates live: URL, code, and SVG as you type, the server-rendered preview image a moment later (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" — as a PNG at standard pixel density.

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 renders a raster image (PNG, WebP, or JPEG) 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 &.

The segment only counts as an image request if it starts with a digit — so an address like ?utm_source=… simply shows the generator page. Besides the query form, the server also accepts a path form without the question mark (/tools/ph/800x600-3c4955-eeeeee/). It only suits the simple case, though: text in that form may consist only of ASCII letters, digits, and underscores, and options such as &format= don't reach the tool. The tool itself always produces the query form — use it whenever spaces, encoded characters, or options are involved.

Required parameters

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". Hex values are case-insensitive; the 3-digit shorthand is expanded as in CSS (fff = ffffff).

Optional query parameters

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

Example URLs

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

# the same with shorthand hex
https://www.jpkc.com/tools/ph/?600x400-ccc-333/

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

# larger starting size (96 px instead of the automatic 84 px)
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

# WebP at double pixel density (1600 x 1200 pixels)
https://www.jpkc.com/tools/ph/?800x600-3c4955-eeeeee-Hero/&format=webp&scale=2

# accented letter and hyphen in the text: "Café Pop-up"
https://www.jpkc.com/tools/ph/?800x600-3c4955-eeeeee-Caf%C3%A9+Pop%2Dup/

Validation and limits

The server validates every address before it renders an image:

• The segment must have 3 or 4 parts. A hyphen in the text would create a fifth part — hence %2D.
• An unencoded /, &, or # ends the request at that point: / closes the segment, & starts the next option, and the browser doesn't send anything from # onwards at all. The text is then silently cut off — ?800x600-fff-000-On/Off/ becomes "On", ?800x600-fff-000-A&B/ becomes "A", and the server returns an image with the shortened text without any error (HTTP 200). Write these characters as %2F, %26, and %23; a URL copied from the tool already has that done.
• The first part must match the pattern WIDTHxHEIGHT made of digits exactly (at most 5 digits each; notations like 1e3x10 are rejected). Within that pattern the dimensions are hard-clamped to 1–3200: 5000x100 yields a 3200 × 100 image, 0x100 a 1 × 100 image.
• Background and text colour must be 3 or 6 hex digits.
• The text must be valid UTF-8. + becomes a space, then percent-encodings are decoded. What survives is printable Latin-1 — the character set of the font in use, Droid Sans: ASCII, umlauts, ß, accented letters, and characters such as §, °, or ©. Everything else (curly quotes, en and em dashes, €, emoji) is removed, runs of spaces are then collapsed, and the rest is cut to 255 characters.
• format must be a format the server supports, scale must be 1, 2, or 3 — and the larger side times scale must not exceed 3200 pixels (2000x1000 with &scale=2 is rejected).
• Error response: if an address doesn't fit, the server answers with HTTP 400 and plain text (text/plain) of the form Invalid placeholder URL: <reason>, followed by the format and an example. In an <img> this shows up as a broken image; open the address directly in the browser and you can read the reason.

How the text fits the image

The raster image and the SVG set the text by the same rule, which is why both look the same:

1. Starting size: with Text size on Auto, it's the shorter image side divided by 6 (one line) or by 7.5 (custom text plus dimensions line), at least 5 and at most 170 px. A preset (small 16, medium 32, large 64, xlarge 96 px) replaces this starting size.
2. Wrapping: the custom text is wrapped at word boundaries as soon as a line would get wider than 90 % of the image. A single word that is too wide on its own stays on a line by itself.
3. Shrinking: if not every line fits within 90 % of the width, or the whole block within 90 % of the height, the font shrinks in 10 % steps and the wrapping is recalculated — until everything fits or the minimum size of 5 px is reached.

The lines sit centred in the image at 1.2× line spacing; the dimensions line "W x H" always comes last. That makes the presets caps: a long text is set smaller even with xlarge, so it doesn't run over the edge.

Dimensions

The Dimensions card has two number fields, Width and Height (1–3200 each). Values outside that range are set to the limit when you leave the field. A swap button (arrow icon, "Swap width and height") 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 and Text, each driven by a colour picker (hex format without transparency, with twelve predefined swatches). You can also type directly: #fff or fff are understood just like #ffffff, and when you leave the field it shows the full 6-digit form again. A swap button ("Swap colors") trades the background and text colour — useful for quickly comparing a light and a dark variant. In the URL scheme these values appear as 6-digit hex without #.

Below the fields the tool shows the contrast between text and background colour as a ratio, for instance Contrast 7.95:1 for the defaults (calculated with the WCAG formula for relative luminance). Below 4.5:1 the readout turns into a warning and adds "below 4.5:1, the text may be hard to read".

Text options (Text)

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

• Show text on the image — the master switch for text. Off → the image is a plain colour fill (equivalent to notext=1).
• Custom text — your own caption (max. 255 characters). Anything from printable Latin-1 is allowed, including umlauts, accented letters, and punctuation. Characters the font doesn't have are left out and listed below the field: "Not in the font, left out: …". Leave it empty → the image shows only the dimensions (as the placeholder text "Leave empty to show the size" points out). The tool encodes hyphens and plus signs in the URL for you.
• Also show the size (width × height) — shows or hides the dimensions line in addition to the custom text. This switch is only active when text is shown and a custom text is set — otherwise the image would have no text at all. Off → only the custom text appears (equivalent to nodim=1).
• Text size — Auto (fits the image), Small (max. 16 px), Medium (max. 32 px), Large (max. 64 px), or Extra large (max. 96 px). How the size comes about is explained under How the text fits the image; the tool reminds you with "Long text is wrapped and shrunk so it always fits."

When the custom text and the dimensions are both visible, the (possibly multi-line) custom text sits on top and the dimensions below.

Preview and code output

Four cards on the left show the result:

• Preview — the preview image as the server delivers it ("image from the server"), with a badge naming the current dimensions (with a suffix such as "@2x" at higher pixel densities). The preview updates automatically, about half a second after your last change; it always loads the standard-density version. There's no button to refresh it, and you don't need one.
• HTML — the finished <img> tag including src, alt, width, and height, with a Copy button. alt is your custom text or "W×H placeholder"; special characters are HTML-escaped. At a Pixel density of 2× or 3× the tag also gets a srcset with the standard and the high-density version, while width and height keep the CSS dimensions.
• Image URL — the bare image URL following the scheme above, including format and scale, also with a Copy button.
• URL format — a quick reference of the URL format and its options right inside the tool, listing the formats this server actually offers.

Format, pixel density and download (Image file)

The Image file card sets the raster format and offers two downloads:

• Format — PNG, WebP, or JPEG. The list only shows formats the server can produce. Your choice applies to the Preview, Image URL, HTML, and the download.
• Pixel density — 1× (standard), 2× (Retina), or 3×. The image gets correspondingly more pixels, while the text stays the same size relative to it. The 3200-pixel limit applies to the result: at 3× the longest side can be at most 1066 pixels.
• Download PNG / WebP / JPEG — the button carries the chosen format in its label and saves the server-rendered image as placeholder-WxH.png, or at higher density as something like placeholder-WxH@2x.webp. This path uses exactly the URL scheme.
• Download SVG — saves the browser-generated SVG variant as placeholder-WxH.svg.

SVG output in detail

The SVG (no server needed) 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 — the raw <svg> source: a <rect> as the fill and a <text> with one <tspan> per line, centred horizontally.
• CSS — a ready-made CSS line background-image: url('data:image/svg+xml,…'); to drop straight into your stylesheet.
• IMG — an <img> with an embedded SVG data URI that works without an external file and without a server request.

The SVG takes its lines and font size exactly from the text layout rule; to do so, the tool measures in the browser with the same Droid Sans font as the server and without kerning. The SVG itself names the font chain 'Droid Sans', 'Noto Sans', Roboto, Arial, sans-serif — if the viewer doesn't have Droid Sans installed, the next font steps in and the text width may differ slightly. The SVG always has the CSS dimensions; pixel density plays no role here, because a vector graphic stays sharp at any resolution anyway.

Unlike the raster 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 — Open Graph / Facebook 1200 × 630, X / Twitter post 1200 × 675, Instagram square 1080 × 1080, Instagram portrait 1080 × 1350, Story / Reel 1080 × 1920, 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 QHD 2560 × 1440, MacBook Pro 1512 × 982.
• Common — Square small 150 × 150, Square medium 300 × 300, Square large 600 × 600, Thumbnail 150 × 100, Preview 4:3 400 × 300, Hero 1200 × 400, Video 16:9 1280 × 720.

Caching and operation — in brief

• Server output formats: PNG (image/png) always, WebP and JPEG (quality 90) where the server's graphics library supports them. SVG is a browser-only feature.
• Caching: served images carry Cache-Control: public, max-age=31536000, immutable — the URL describes the image completely, so browsers and CDNs may keep it for a year.
• Dimensions: 1–3200 px per side, hard-clamped; with scale the limit applies to the result in pixels.
• Text: max. 255 characters, printable Latin-1; + = space, %2D = "-", %2B = "+", %2F = "/", %26 = "&", %23 = "#".
• Colours: 6- or 3-digit hex each, without #.
• Error behaviour: an invalid URL → HTTP 400 with a plain-text hint, not cached.
• Rate limit: at most 300 newly rendered images per minute and IP address; beyond that the server answers with HTTP 429 and a Retry-After header. Repeat requests served from the browser cache never reach the server and therefore don't count.
• No account, no history: the tool doesn't remember your settings; every image is created from its URL alone.

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.