Placeholder API

The Placehold service runs on a Node adapter deployment, selecting images from local storage (or manifest-defined remotes) based on path and query data. Requests preferring text/html render human docs; every other user agent receives an image or SVG diagnostic.

Endpoint

GET {category?}/{tags?}/{dimensions?}.{format?}

All parameters are optional. When the path lacks dimensions, specify them via query parameters.

Example Requests

  • Basic square placeholder

    https://img.krsz.dev/design/512?seed=profile-card

  • Landscape with filters

    https://img.krsz.dev/nature/forest/1600x900.webp?tags=night,aurora

  • Query parameters only

    https://img.krsz.dev/?category=workspace&tags=desk+flatlay&w=1280&h=720

Parameters

ParameterRequiredWhereDescription
dimensionsoptionalpath or queryAccepts 512, 1200x800, 1200/800, 1200:800 or ?w=1200&h=800. Defaults to square if only one side provided.
formatoptionalextension or ?formatjpg, png, webp, avif, gif. If omitted, we negotiate from the Accept header.
categoryoptionalfirst path segment or ?categoryHigh-level grouping; multiple values allowed with comma/space/+/pipe separators.
tagsoptionaladditional path segments or ?tagsEach supplied tag must exist on the image variant (AND matching). Multiple delimiters supported.
orientationoptional?orientationlandscape, portrait, or square. Filters variants before size ranking.
seedoptional?seedDeterministic selection. Same seed + filters returns the same variant.
placementoptional?placementHuman-friendly placement key that combines with keywords to derive a stable seed.
cdnoptional?cdn=truePrefer R2/static assets over remote demo URLs when available.

Response Headers

  • X-Placeholder-Id

    Matched image identifier.

  • X-Placeholder-Dimensions

    Actual width × height served.

  • X-Placeholder-Format

    Resolved file format.

  • X-Placeholder-Seed

    Echoes the supplied seed or placement-derived seed.

  • X-Placeholder-Cache

    hit/miss signal for the on-disk cache under PLACEHOLDER_CACHE_DIR.

  • X-Placeholder-Cache-Key

    SHA1 hash of the cache entry for debugging.

  • ETag

    Content hash derived from cache entry size + mtime for conditional requests.

  • Last-Modified

    UTC timestamp when the cached asset was (re)generated.

  • X-Placeholder-Fallback

    Only present on SVG diagnostic responses.

Status Codes

  • 200 – Image stream or SVG diagnostic delivered successfully.
  • 404 – No variant matched the supplied filters.
  • 429 – Automated agent exceeded the published rate limit.
  • 5xx – Upstream storage or remote source failed; retries will iterate alternative variants.

Caching

First requests create resized versions under `PLACEHOLDER_CACHE_DIR` (default `./cached`). Subsequent calls stream from disk, so keep the cache directory on fast storage and mount it when running in Docker.

HEAD requests report metadata only after a cached render exists. Issue a GET once to warm the cache if you rely on HEAD-prefetching.

Keyword index

The dataset currently exposes 20,345 keywords, 214 categories, and 3,585 tags. Fetch /api/keywords for the full list; highlights are below. Want book jackets only? Use the covers category to filter to Polar + Sonora manifests.

Categories

  • nature (14190)
  • outdoors (12979)
  • plant (6402)
  • animal (4114)
  • tree (1669)
  • flower (1240)
  • landscape (1174)
  • mammal (1003)
  • water (872)
  • person (803)
  • scenery (621)
  • sky (527)
  • building (486)
  • light (392)
  • human (333)
  • bird (282)
  • blossom (179)
  • mountain (167)
  • sea (164)
  • food (142)
  • books (130)
  • covers (130)
  • polar (112)
  • wildlife (99)

Tags

  • nature (14190)
  • outdoors (12979)
  • plant (9629)
  • animal (6524)
  • tree (6165)
  • landscape (6121)
  • scenery (6093)
  • water (5998)
  • sky (5391)
  • mountain (4956)
  • sea (4240)
  • ocean (3980)
  • land (3967)
  • flower (3298)
  • vegetation (3248)
  • blossom (3235)
  • building (3228)
  • person (3146)
  • snow (3146)
  • light (3145)
  • human (2933)
  • mammal (2880)
  • ice (2870)
  • weather (2835)

Keywords

  • nature (14190)
  • outdoors (12979)
  • plant (9629)
  • animal (6524)
  • tree (6165)
  • landscape (6121)
  • scenery (6093)
  • water (5998)
  • sky (5391)
  • mountain (4956)
  • sea (4240)
  • ocean (3980)
  • land (3966)
  • flower (3298)
  • vegetation (3250)
  • blossom (3235)
  • building (3228)
  • snow (3149)
  • person (3148)
  • light (3145)
  • human (2934)
  • ice (2889)
  • mammal (2887)
  • weather (2854)
  • mountain range (2844)
  • coast (2543)
  • sunset (2449)
  • bird (2428)
  • forest (2426)
  • wilderness (2364)
  • wildlife (2330)
  • flora (2295)
  • road (2270)
  • green (2166)
  • grass (2160)
  • sunlight (2143)
  • flare (2108)
  • fir (2086)
  • conifer (2075)
  • abies (2061)
  • leisure activities (2040)
  • sunrise (2028)
  • cloud (1993)
  • shoreline (1993)
  • rock (1981)
  • night (1951)
  • beach (1925)
  • countryside (1871)
  • adventure (1828)
  • winter (1818)

Automation guidance

Respect llms.txt at /llms.txt. Limit automated clients to 120 requests per minute per IP; contact ops@krisztiaan.dev if you need more.