Usage

Drop in anywhere. Works instantly.

Three patterns — img tag, fetch API, or the drop-in SDK with automatic shimmer loading.

<!-- Prompt + style preset -->
<img src="https://pixsum.dev?prompt=a+barista+pouring+latte+art&preset=documentary&w=1200&h=800&key=YOUR_KEY" />

<!-- Preset standalone (uses built-in example subject) -->
<img src="https://pixsum.dev?preset=cinematic&w=1280&h=540&key=YOUR_KEY" />

<!-- Custom prompt, 16:9, webp -->
<img src="https://pixsum.dev?prompt=empty+Tokyo+street+at+dusk&preset=street&w=1200&ar=16:9&fmt=webp&key=YOUR_KEY" />
// Single image — prompt + style preset
const url = `https://pixsum.dev?prompt=${encodeURIComponent(prompt)}&preset=documentary&w=1200&h=800&key=YOUR_KEY`;

// Batch: one brief → many coherent images
const res = await fetch('https://pixsum.dev/batch?key=YOUR_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    context: "Team offsite in Kyoto. Warm lantern light. Candid, documentary, 35mm film grain.",
    images: [
      { role: 'hero', w: 1200, h: 630 },
      { role: 'thumbnail', w: 400, h: 250, count: 4 }
    ]
  })
});
<!-- Drop in the SDK -->
<script src="https://pixsum.dev/pixsum.js" data-key="YOUR_KEY"></script>

<!-- Single image — prompt + style preset -->
<img data-pixsum-prompt="a professional at their desk, warm natural light"
     data-pixsum-preset="corporate-portrait" data-w="400" data-h="400" />

<!-- Batch story card -->
<div data-pixsum-batch>
  <data value="Team offsite in Kyoto. Candid, warm, documentary, 35mm film grain."></data>
  <img data-pixsum-role="hero"      data-w="700" data-h="400" />
  <img data-pixsum-role="thumbnail" data-w="160" data-h="100" />
</div>
<!-- Shimmer + fade-in handled automatically -->

Presets

6 photographic styles.

Documentary, cinematic, editorial, street, architectural and more. Each preset is a photographic style recipe — camera, lens, lighting, colour grade — baked into a single word.

Batch API Growth

One brief. Many coherent images.

Describe your scene once. Pixsum expands it into tonally consistent prompts — same mood, same light, same story.

Batch API

fetch('https://pixsum.dev/batch', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_KEY' },
  body: JSON.stringify({
    context: ,
    slots: [
      { role: 'hero',  w: 1200, h: 630 },
      { role: 'thumb', w: 400,  h: 400 },
      { role: 'thumb', w: 400,  h: 400 },
      { role: 'thumb', w: 400,  h: 400 },
      { role: 'thumb', w: 400,  h: 400 }
    ]
  })
})

Image Manipulation Studio

Transform every image in the URL.

Apply post-processing adjustments at the edge — blur, brightness, contrast, saturation. Parameters baked into the cache key, so every unique combination is served instantly after the first hit.

/* Greyscale — saturation=0 */
https://pixsum.dev?prompt=a+rainy+tokyo+street+at+night&saturation=0&preset=street&key=YOUR_KEY

/* Dramatic — high contrast, slight blur */
https://pixsum.dev?prompt=a+boxer+in+a+gym&contrast=1.6&blur=3&preset=documentary&key=YOUR_KEY

/* Faded / vintage — low contrast, desaturated */
https://pixsum.dev?prompt=polaroids+on+a+wooden+table&contrast=0.7&saturation=0.5&brightness=1.2&key=YOUR_KEY

/* Fetch API */
const url = `https://pixsum.dev?prompt=${encodeURIComponent(prompt)}&saturation=0&contrast=1.4&key=${KEY}`;
const res = await fetch(url);
const blob = await res.blob(); // cached at edge after first generation

blur=0–100

Gaussian blur. Great for backgrounds and depth-of-field effects.

brightness=0.5–2

Exposure adjustment. 1 is unchanged, 2 is twice as bright.

contrast=0.5–2

Contrast curve. Push above 1.4 for dramatic, cinematic looks.

saturation=0–2

Colour intensity. Set to 0 for full greyscale.

camera=

Camera body. leica, sony, hasselblad, arri, phase-one, canon.

lens=

Lens choice. 35mm, 50mm, 85mm, 100mm-macro, anamorphic, tilt-shift, wide.

film=

Film stock. portra-400, fuji-400h, velvia-50, vision3, ilford-hp5, tri-x, ektar.

grade=

Colour grade. teal-orange, matte, crushed-blacks, bleach-bypass, bw, fuji.

Why Pixsum

The image API that replaces your stock library.

⚡

Edge cached

First hit generates & caches. Every repeat is served from Cloudflare's edge in ~10ms.

🎨

Craft-quality style presets

Photographic style presets with real photography direction. Camera, lens, lighting, colour grade — all baked in. Any subject, any preset.

🧠

Batch coherence

Send one context brief, get a story card. LLM expands into consistent prompts — same people, same light.

🔌

Drop-in SDK

3KB, zero deps. Annotate HTML with data attributes. Shimmer + fade-in handled automatically.

🧩

Multi-model

Swap the underlying image model with a single config change. Gemini, DALL-E, Flux — same API, different engine.

🔄

Any stack

Works anywhere an img tag works. React, Vue, Svelte, plain HTML. No SDK required — just a URL.