GET/placeholder/*0.5 credits per call · 1-year immutable cache

// PRODUCT · PLACEHOLDERS

Placeholders.

BlurHash and dominant-color tiles served as real images. Pass a hash or a source — get a sub-kilobyte placeholder back, immutably cached for a year.

quick start

# Decode a BlurHash · 1200×675 tile
curl 'https://demo.imgapis.com/placeholder/blurhash?blurhash=LEHV6nWB2yk8pyo0adR*.7kCMdnj&w=250&h=250'

Live preview · streamed from demo.imgapis.com

Variant · 01GET /placeholder/blurhash

Placeholder · BlurHash.

Render a blurred low-res preview while the real image streams in — pass the hash directly or derive it from a URL.

Decode a BlurHash · 250×250 placeholder
// preview

Derive BlurHash from an image URL
// preview

// parameters9fields

Param

Type

Default

Description

blurhashone of blurhash / src

stringType

—Default

A BlurHash string to decode.

srcone of blurhash / src

stringType

—Default

Source image. Full URL, source-alias form (<source-name>/<path>), or path-sugar /placeholder/blurhash/<source-name>/<path>. Server derives the BlurHash from it.

wOptional

integer (1–2048)Type

—Default

Output width in pixels. Required with blurhash; optional with src (falls back to intrinsic).

hOptional

integer (1–2048)Type

—Default

Output height in pixels.

fitOptional

enumType

containDefault

With src, defaults to contain. Pass cover to force exact w × h.

containcover

dprOptional

number (0–2)Type

1Default

Device-pixel-ratio multiplier.

punchOptional

numberType

1Default

BlurHash decoder contrast boost.

qualityOptional

integer (1–100)Type

80Default

Encoder quality. Applies to lossy formats.

formatOptional

enumType

—Default

Output format. Accept-negotiated when omitted (avif > webp > png).

avifjpegjpgnocompresspngwebp

Variant · 02GET /placeholder/color

Placeholder · Color.

Drop a solid-color tile (or auto-color from an image) for instant LQIP and offline-friendly skeletons.

Solid hex color · 250×250 PNG
// preview

Extract dominant color from URL
// preview

// parameters8fields

Param

Type

Default

Description

colorone of color / src

stringType

—Default

Hex color. Accepts #rgb, #rgba, #rrggbb, #rrggbbaa. Leading # is optional.

srcone of color / src

stringType

—Default

Source image. Full URL, source-alias form (<source-name>/<path>), or path-sugar /placeholder/color/<source-name>/<path>. Server extracts the dominant color from it.

wOptional

integer (1–2048)Type

—Default

Output width in pixels. Required with color; optional with src.

hOptional

integer (1–2048)Type

—Default

Output height in pixels.

fitOptional

enumType

containDefault

With src, defaults to contain. Pass cover to force exact w × h.

containcover

dprOptional

number (0–2)Type

1Default

Device-pixel-ratio multiplier.

qualityOptional

integer (1–100)Type

80Default

Encoder quality. Applies to lossy formats.

formatOptional

enumType

—Default

Output format. Accept-negotiated when omitted (avif > webp > png).

avifjpegjpgnocompresspngwebp

// COOL USAGES

Render the placeholder before the bytes arrive.

// 01

LCP-safe hero placeholders

Sub-2 kB PNG fills the hero box before the AVIF lands. Largest-contentful-paint stays green without shipping a BlurHash decoder to every visitor.

// 02

Offline-friendly skeletons

Solid-color tiles cache in your service worker; the full image swaps in when network comes back. Offline-friendly UI without a separate asset pipeline.

// 03

List / grid lazy-load

Color tile for every card in the feed; swap in the real image on IntersectionObserver. Hundreds of images per scroll, one URL grammar.

// 04

Dominant-color empty states

/placeholder/color?src=… extracts the dominant color AND serves the tile in one URL. No /info round-trip, no client-side color math.

// KEEP EXPLORING

// /product/info

Info API

Extract the BlurHash or dominant color first, cache it, then render here.

// /product/transform

Transform API

Same URL grammar — once the real image arrives, swap to /transform.