# Placeholder.photo full AI-ready reference > Placeholder.photo provides free, URL-first visual placeholders for websites, apps, prototypes, tests, documentation and design mockups. Canonical origin: [https://placeholder.photo](https://placeholder.photo/) Operator: [Jansma VIP](https://jansma.vip/) Short discovery file: [llms.txt](https://placeholder.photo/llms.txt) Canonical full reference: [llms-full.txt](https://placeholder.photo/llms-full.txt) Compact agent contract: [agent-instructions.txt](https://placeholder.photo/agent-instructions.txt) Installable agent skill: [SKILL.md](https://placeholder.photo/SKILL.md) Downloadable skill package: [placeholder-photo-skill.zip](https://placeholder.photo/placeholder-photo-skill.zip) Live capabilities: [status JSON](https://placeholder.photo/status?format=json) ## Product contract - The public image URL is the API. - Ordinary use requires no account, login, API key, SDK, subscription or payment. - Direct cross-origin embedding and hotlinking are supported without JavaScript, a session or a Referrer header. - Public generated visual output carries only the subtle `placeholder.photo` watermark. - There is no documented public unbranded switch. - The same normalized configuration, renderer version and seed produces deterministic output. - Generated derivatives are cached by their complete normalized render configuration. - The service does not call third-party image, avatar, font or live AI-generation APIs during ordinary rendering. - Curated photo masters are locally stored and reviewed before publication. - Placeholder.photo is not an arbitrary public AI prompt service or visitor-upload editor. ## Agent integration rules 1. Prefer a direct HTTPS image URL for temporary artwork. 2. Use only the routes and parameters documented here or in the [parameter reference](https://placeholder.photo/parameters). 3. Use a stable, human-readable and non-sensitive `seed` whenever an image identity must remain repeatable. 4. Never place passwords, access tokens, personal records or other secrets in paths, text, seeds or query strings. 5. URL-encode custom text, brand names, taglines and seeds. 6. Check the HTTP status. An image-looking response can still carry a meaningful 4xx or 5xx status. 7. In HTML, provide explicit `width` and `height` plus a deliberate `alt` value. Use `alt=""` for a purely decorative placeholder. 8. Use a right-sized output. Do not request a multi-megapixel render for a small card or avatar. 9. Do not add timestamps or random values to deterministic URLs unless a genuinely new visual is wanted. 10. Do not invent a public watermark-removal or unbranded parameter. ## Common syntax The preferred size syntax is `{width}x{height}`. A single number creates a square. Dimensions must be between 1 and 4096 pixels and the total rendered pixel count is bounded. Supported format suffixes are `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` and `.avif`. GIF is static. AVIF should be used only when the [live status endpoint](https://placeholder.photo/status?format=json) reports support. The visual generator's `Auto` setting chooses the smallest suitable available format: normally SVG for compact vector-like output, and AVIF (with WebP fallback) for curated photos. Selecting a self-hosted render font can make an embedded SVG larger, so Auto may choose the smallest supported raster format. Copy the resulting explicit extension for stable production integration. Common query parameters: - `dpr`: integer `1`, `2` or `3`; raster pixel dimensions are multiplied while intended display dimensions remain unchanged. - `quality`: integer `40` through `100` for raster encoding. - `seed`: deterministic identity string, maximum 128 bytes. - `download=1`: request an attachment instead of inline display. Colours use three, four, six or eight hexadecimal digits. A leading `#` must be URL-encoded and is unnecessary, so plain values such as `6D5DFC` are preferred. Equivalent colour casing is normalized internally. ## Classic placeholders Preferred routes: ```text /{width}x{height}[.{format}] /{size}[.{format}] /{width}x{height}/{background}/{text-colour}[.{format}]?text=... ``` Examples: ```text https://placeholder.photo/800x600 https://placeholder.photo/256.svg https://placeholder.photo/800x450/6D5DFC/FFFFFF?text=Dashboard https://placeholder.photo/800x450.svg?transparent=1&color=5B49DD&text=Transparent ``` Parameters: - `text`: custom text; encoded line breaks are supported, with at most five lines and 180 characters. - `bg`: background colour or `transparent`. - `color`: text colour. - `font`: `system`, `humanist`, `serif`, `mono`, `rounded`, `poppins`, `space`, `developer`, `pixel` or `retro`. - `fontSize`: `0` for automatic sizing or an integer through 512. - `weight`: `400`, `500`, `600`, `700` or `800`. - `italic`: boolean. - `align`: `left`, `center` or `right`. - `valign`: `top`, `middle` or `bottom`. - `lineHeight`: decimal from `0.8` through `2.5`. - `letterSpacing`: decimal from `-4` through `24`. - `padding`: bounded non-negative integer. - `opacity`: decimal from `0` through `1`. - `border`: bounded border width. - `borderColor`: border colour. - `radius`: bounded corner radius. - `rounded`: boolean shortcut for the maximum appropriate radius. - `transparent`: boolean. JPEG cannot represent transparency and returns HTTP 400 when transparency is requested. Prefer SVG for vector-like output, PNG for universal lossless alpha, or WebP/AVIF for compact modern raster alpha. ## Gradients Route: ```text /gradient/{width}x{height}[.{format}] ``` Example: ```text https://placeholder.photo/gradient/1200x630.svg?colors=6D5DFC,29C7AC,FFCF70&type=linear&angle=135 ``` Parameters: - `colors`: comma-separated list of two through five hex colours. - `type`: `linear` or `radial`. - `angle`: integer `0` through `360`. - `intensity`: decimal `0.1` through `2`. - `softness`: integer `0` through `100`. - `grain`: integer `0` through `40`. - `opacity`: decimal `0.05` through `1`. ## Patterns Route: ```text /pattern/{style}/{width}x{height}[.{format}]?seed=... ``` Styles: `dots`, `grid`, `diagonal`, `horizontal`, `vertical`, `checkerboard`, `crosses`, `waves`, `geometric`, `noise`, `grain`, `paper` Example: ```text https://placeholder.photo/pattern/grid/960x540.svg?bg=F7F7FB&color=5B49DD&scale=32&seed=docs-grid ``` Parameters: - `bg`, `color`: background and foreground colours. - `scale`: integer `4` through `256`. - `spacing`: integer `0` through `128`. - `density`: decimal `0.2` through `2`. - `rotation`: integer `0` through `360`. - `opacity`: decimal `0.02` through `1`. - `seed`: deterministic pattern identity. ## Procedural abstract images Route: ```text /abstract/{style}/{width}x{height}[.{format}]?seed=... ``` Styles: `marble`, `liquid`, `fluid`, `mesh`, `blobs`, `aurora`, `waves`, `smoke`, `glow`, `geometric`, `low-poly`, `soft-shapes`, `fields`, `pastel`, `luxury`, `dark`, `organic` Example: ```text https://placeholder.photo/abstract/aurora/1200x630.webp?colors=12152B,6D5DFC,29C7AC,FFCF70&seed=homepage-hero ``` Parameters: - `colors`: two through five comma-separated hex colours. - `intensity`: integer `0` through `100`. - `contrast`: integer `0` through `100`. - `softness`: integer `0` through `100`. - `blur`: integer `0` through `32`. - `grain`: integer `0` through `40`. - `complexity`: integer `10` through `100`. - `seed`: deterministic abstract identity. ## Curated photos Routes: ```text /photo/{category}/{subcategory}/{width}x{height}[.{format}]?set=v2&seed=... /photo/{category}/{subcategory}/{asset-id}/{width}x{height}[.{format}] ``` Examples: ```text https://placeholder.photo/photo/business/office/1200x630.webp?set=v2&seed=client-demo&mode=hero https://placeholder.photo/photo/business/office/ph-0001/800x600.webp?mode=card ``` Use `set=v2` to select deterministically from the expanded catalogue. Omitted `set` preserves the frozen launch `v1` mapping. Use an exact permanent `ph-####` ID when the photo identity must never change. Launch categories include business/office, technology/saas, construction/site, trades/plumbing, automotive/workshop, food/restaurant, real-estate/interior, retail/store, hospitality/hotel, fitness/studio, people/professional and logistics/warehouse. Photo output is raster only. Prefer WebP, JPEG, PNG or AVIF. Parameters: - `fit`: `cover`, `contain` or `crop`. - `position`: `center`, `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left` or `bottom-right`. - `focalX`, `focalY`: decimal `0` through `1`. - `blur`: integer `0` through `32`. - `vignette`: integer `0` through `100`. - `grayscale`: boolean. - `saturation`: integer `0` through `200`. - `brightness`, `contrast`: integer `40` through `160`. - `opacity`: decimal `0.05` through `1`. - `overlay`: hex colour or `none`. - `overlayOpacity`: decimal `0` through `0.85`. - `duotone`: exactly two comma-separated colours. - `border`, `borderColor`, `radius`: bounded framing controls. - `mode`: `none`, `hero`, `background` or `card`. - `set`: `v1` or `v2`. ## Mock logos Route: ```text /logo/{width}x{height}[.{format}]?name=...&seed=... ``` Example: ```text https://placeholder.photo/logo/800x300.svg?name=Northstar&tagline=Studio&mode=symbol-text&seed=northstar-demo ``` Parameters: - `name`, `initials`, `tagline`. - `mode`: `wordmark`, `monogram`, `badge`, `symbol-text`, `abstract`, `horizontal`, `stacked` or `icon`. - `shape`: `none`, `circle`, `square`, `rounded`, `pill`, `hexagon`, `ring`, `badge` or `blob`. - `font`, `weight`, `letterSpacing`, `textColor`. - `primary`, `secondary`, `bg`. - `gradient`, `shadow`: booleans. - `border`: integer `0` through `32`. - `preset`: `custom`, `navbar`, `horizontal`, `stacked`, `favicon`, `app-icon`, `social-avatar`, `watermark`, `icon` or `badge`. - `seed`: deterministic mock-brand identity. These are temporary fictional design aids, not verified identities or an AI logo-design service. Avoid names or marks that impersonate real organizations. ## Avatars Route: ```text /avatar/{size}[.{format}]?style=...&seed=... ``` Examples: ```text https://placeholder.photo/avatar/256.svg?name=Alex+Morgan https://placeholder.photo/avatar/256.svg?style=abstract&seed=user-123 https://placeholder.photo/avatar/512.svg?style=layered-plus&seed=user-123&hair=coils&clothing=hoodie&hairColor=3B2A23&clothingColor=6D5DFC ``` Base parameters: - `style`: `initials`, `abstract`, `identicon`, `layered`, `illustrated` or `layered-plus`. - `name`, `initials`; `text` is accepted as a manual-initials alias. - `shape`: `circle`, `rounded` or `square`. - `bg`, `primary`, `secondary`, `color`. - `font`, `weight`, `border`, `seed`. Layered+ parameters: - `face`: `auto`, `oval`, `round`, `square`, `long`. - `skin`: `auto`, `porcelain`, `light`, `warm`, `medium`, `olive`, `tan`, `brown`, `deep`. - `hair`: `auto`, `short`, `crop`, `wave`, `bun`, `curly`, `bald`, `long`, `bob`, `coils`, `afro`, `sidepart`. - `clothing`: `auto`, `tshirt`, `shirt`, `hoodie`, `blazer`, `workwear`, `sweater`, `turtleneck`, `overalls`. - `eyes`: `auto`, `round`, `soft`, `smile`, `wide`. - `brows`: `auto`, `soft`, `straight`, `arched`. - `nose`: `auto`, `small`, `straight`, `wide`. - `mouth`: `auto`, `smile`, `neutral`, `open`, `grin`. - `facialHair`: `auto`, `none`, `stubble`, `moustache`, `goatee`, `beard`. - `accessory`: `auto`, `none`, `round-glasses`, `square-glasses`, `sunglasses`, `earring`. - `backgroundStyle`: `solid`, `gradient`, `halo`, `dots`, `waves`. - `skinColor`, `hairColor`, `clothingColor`, `eyeColor`, `mouthColor`, `accent`, `borderColor`. Omitting a Layered+ option keeps deterministic seeded selection. Use `bg=transparent` only with SVG, PNG, WebP or AVIF. ## Boolean values and aliases Preferred boolean values are `1` and `0`. The parser also accepts `true`, `false`, `yes`, `no`, `on` and `off`. The public documentation teaches one preferred spelling. Historical aliases such as `background` for `bg`, `foreground` for `color`, `font_size` for `fontSize` and `border_width` for `border` remain accepted for compatibility. ## Responses, caching and failure handling - Successful image requests return the correct image MIME type directly or through a temporary redirect to the immutable stored derivative. - Deterministic derivatives receive content-addressed storage identities and long-lived cache headers. - Repeated identical normalized requests reuse the same derivative instead of re-rendering. - Invalid image requests return a small branded SVG explanation with the meaningful 4xx or 5xx status. - HTTP 400 indicates an invalid combination or value; 404 indicates a missing route or gallery asset; 413 indicates a render limit; 429 indicates too many new uncached combinations; 501 indicates a format unavailable on the current server; and 503 indicates temporary capacity or storage pressure. - Image endpoints allow cross-origin embedding with `Access-Control-Allow-Origin: *`. - During temporary persistent-storage failure, bounded degraded rendering may return a correct uncached image with `Cache-Control: no-store`. Capacity is intentionally restricted to protect the shared origin. ## Accessibility guidance Recommended meaningful image: ```html Dashboard image placeholder ``` Recommended decorative image: ```html ``` Do not copy visible placeholder text mechanically into every `alt` attribute. Describe the image's purpose when it conveys meaning; use an empty alt value when it is purely decorative. ## Privacy and safety - Public image URLs are normally logged by web infrastructure, so text and seeds must be treated as public URL data. - The website uses Consently for privacy choices. Google Tag Manager runs only on normal HTML pages; image and API responses contain no consent banner, analytics or advertising scripts. - Generator fields and preview content are designated for masking in Microsoft Clarity recordings. - Do not use generated mock identities for deception, endorsement claims or impersonation. - Do not automate intentionally unique render combinations to exhaust CPU, bandwidth or storage. ## Public documentation - [Developer documentation](https://placeholder.photo/docs) - [Parameter reference](https://placeholder.photo/parameters) - [Copy-ready examples](https://placeholder.photo/examples) - [Web and social presets](https://placeholder.photo/image-sizes) - [Compatibility guide](https://placeholder.photo/compatibility) - [Official migration CLI](https://placeholder.photo/docs/migration-cli) - [Visual URL builder](https://placeholder.photo/generator) - [Curated gallery](https://placeholder.photo/gallery) - [Image license](https://placeholder.photo/image-license) - [Privacy](https://placeholder.photo/privacy) - [Cookie policy](https://placeholder.photo/cookies) - [Terms](https://placeholder.photo/terms) - [About and history](https://placeholder.photo/about) - [Changelog](https://placeholder.photo/changelog) - [Service status](https://placeholder.photo/status)