Pixsum docs

URL-based photography. Drop a prompt in, get a hyper-realistic image back — permanently cached at the edge, production ready.

Overview#

Pixsum generates photorealistic AI images on demand. The first request for any unique prompt takes 5–10 seconds to generate. Every subsequent request is served from cache — either from Cloudflare's edge (~10ms) or the origin disk cache (~50ms).

Images are referenced by URL and cached permanently. The same prompt+params always returns the same image. This makes Pixsum safe to use in <img> tags, CSS backgrounds, and anywhere else you'd use a static image URL.

Pricing#

Credits are consumed per generation. Cache hits are free — you only spend a credit when a new image is generated. Credits never expire.

Authentication#

All image requests require an API key. Two key types are available:

The /health endpoint is unauthenticated.

Quickstart#

img tag (simplest)

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

<!-- Preset with default aspect ratio (cinematic = 21:9) -->
<img src="https://pixsum.dev?prompt=a+lone+figure+on+a+rain+soaked+rooftop&preset=cinematic&key=YOUR_KEY" />

fetch API

Copyconst res = await fetch(`https://pixsum.dev?prompt=${encodeURIComponent(prompt)}&preset=documentary&w=1200&h=800`, {
  headers: { 'Authorization': 'Bearer YOUR_SECRET_KEY' }
});
const blob = await res.blob();
img.src = URL.createObjectURL(blob);

Changelog#

GET / GET#

Generate or retrieve a single image. Returns raw image bytes with the appropriate Content-Type header.

Parameters

Examples

Copy# Preset avatar, 200×200
curl "https://pixsum.dev?preset=corporate-portrait&w=400&h=400&key=YOUR_KEY"

# Custom prompt, 16:9, webp
curl "https://pixsum.dev?prompt=tokyo+street+at+night&w=1280&ar=16:9&fmt=webp&key=YOUR_KEY"

# With secret key in header
curl -H "Authorization: Bearer YOUR_SECRET_KEY" \
  "https://pixsum.dev?prompt=cozy+cafe+interior&w=800&h=600"

# Budget mode — 1 credit instead of 4, good for prototypes
curl "https://pixsum.dev?prompt=placeholder+hero&w=1200&h=600&quality=low&key=YOUR_KEY"

Enhance example Growth

Copy# Short prompt — auto art-directed into a full photographic brief
curl "https://pixsum.dev?prompt=coffee+cup&enhance=1&w=800&h=600&key=YOUR_GROWTH_KEY"

# Confirm expansion ran — look for X-Enhanced: true in response headers
curl -I "https://pixsum.dev?prompt=coffee+cup&enhance=1&w=800&h=600&key=YOUR_GROWTH_KEY"
# X-Enhanced: true

POST /batch POST Growth#

Generate a coherent set of images from a single context brief. The API uses an LLM to expand your brief into individual prompts — same people, same lighting, same story across all images. Results are cached: identical requests are instant.

Context can be a string or a structured object. Pass whatever data you have — Pixsum handles the reasoning. See examples below.

Request body

Image slot object

Example — string context

Copycurl -X POST https://pixsum.dev/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -d '{
    "context": "Two friends at a Tokyo ramen bar, late evening. Warm lantern light. Candid, documentary, 35mm film grain.",
    "images": [
      { "role": "hero",      "w": 1200, "h": 630 },
      { "role": "thumbnail", "w": 400,  "h": 400, "count": 4 }
    ]
  }'

Example — structured context object

Pass whatever structured data your app has. Pixsum's LLM extracts the visual story — no prompt engineering required on your side.

Copycurl -X POST https://pixsum.dev/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -d '{
    "context": {
      "title": "Late night ramen in Tokyo",
      "story": "Two old friends catching up after years apart. Their first night in the city together.",
      "people": ["Aiko", "James"],
      "places": ["Shibuya", "Tokyo"],
      "themes": ["friendship", "nostalgia"],
      "period": "Autumn 2024"
    },
    "domain": "memoir",
    "cache_key": "story-42",
    "images": [
      { "role": "hero",      "w": 1200, "h": 630 },
      { "role": "thumbnail", "w": 400,  "h": 400, "count": 4 }
    ]
  }'

Response

Copy{
  "images": [
    { "role": "hero",      "url": "/cache/abc123.jpg", "alt": "Two friends laughing over steaming ramen bowls, warm lantern light", "cached": false },
    { "role": "thumbnail", "url": "/cache/def456.jpg", "alt": "Close-up of chopsticks lifting noodles from steaming bowl",     "cached": false },
    { "role": "thumbnail", "url": "/cache/ghi789.jpg", "alt": "Candid moment mid-laugh, looking away from camera",             "cached": false },
    { "role": "thumbnail", "url": "/cache/jkl012.jpg", "alt": "Wide shot of glowing ramen bar, figures small in the space",    "cached": false },
    { "role": "thumbnail", "url": "/cache/mno345.jpg", "alt": "Two ceramic cups of tea on worn wooden counter",               "cached": false }
  ],
  "context": { /* echoed back */ },
  "count": 5
}

GET /v1/generate GET#

Same as GET / but returns JSON instead of raw image bytes. Useful for integrations where you need the URL, alt text, and cache status before rendering.

Copycurl "https://pixsum.dev/v1/generate?preset=documentary&w=800&h=800&key=YOUR_KEY"

Response

Copy{
  "url":    "https://pixsum.dev/cache/abc123.jpg",
  "alt":    "Artisan bowl of ramen with soft-boiled egg and bamboo shoots",
  "prompt": "Gourmet restaurant dish photography...",
  "cached": true,
  "w":      800,
  "h":      800,
  "fmt":    "jpg",
  "model":  "google/gemini-3.1-flash-image-preview"
}

SDK — Installation#

The Pixsum SDK is a 3KB, zero-dependency script. Drop it in any HTML page — it scans for data-pixsum-* attributes and handles shimmer loading + fade-in automatically.

Copy<script src="https://pixsum.dev/pixsum.js" data-key="YOUR_PUBLIC_KEY"></script>

SDK — Single images#

Copy<!-- Preset standalone -->
<img data-pixsum-preset="corporate-portrait" data-w="400" data-h="400" />

<!-- Prompt + style preset -->
<img data-pixsum-prompt="a barista pouring latte art in a sunlit cafe"
     data-pixsum-preset="documentary" data-w="1200" data-h="800" />

Alt text fallback

Enable globally via the script tag or per-container to use the image's alt attribute as the prompt when no data-pixsum-prompt is set:

Copy<!-- Enable globally -->
<script src="https://pixsum.dev/pixsum.js"
  data-key="YOUR_KEY"
  data-alt-fallback="true"></script>

<!-- Or per-container -->
<img data-pixsum-prompt=""
     data-pixsum-alt-fallback="true"
     alt="barista pouring latte art in a sunlit cafe"
     data-pixsum-preset="documentary" />

<!-- Or via JS -->
<script>Pixsum.init({ altFallback: true });</script>

Alt text that looks like a filename (IMG_4382, DSC_0001) is ignored and returns a clean placeholder instead.

SDK — Batch groups#

Copy<div data-pixsum-batch>
  <!-- Context brief (not rendered) -->
  <data value="Team offsite in Kyoto. Candid, warm, documentary style. Film grain."></data>

  <!-- Image slots -->
  <img data-pixsum-role="hero"      data-w="700" data-h="400" />
  <img data-pixsum-role="thumbnail" data-w="160" data-h="100" />
  <img data-pixsum-role="thumbnail" data-w="160" data-h="100" />
</div>
<!-- Shimmer + fade-in handled automatically ✨ -->

Using presets#

Presets are photographic style recipes that encode lighting, mood, and composition quality. Each preset also includes default equipment (camera, lens, film) — Studio plan users can override any of these with URL params. Browse the full preset gallery to see them live.

6 core photographic style presets are available:

Browse them live on the homepage preset gallery.

Equipment override (Studio): pass camera=, lens=, or film= to override any preset default. For example, ?preset=editorial&camera=leica uses the editorial style but swaps in a Leica body while keeping the 85mm lens and Fuji 400H film from the preset.

Legacy presets (editorial-lifestyle, editorial-travel, studio-product, fine-dining, architectural, and more) remain supported for backward compatibility.

Studio Photography Controls Studio#

Studio plan users can specify the camera body, lens, film stock, colour grade, and photographer style as URL parameters. These override the default equipment defined by a preset — so you get the preset's lighting and mood with your chosen gear.

Copy# Street documentary shot — Leica, 35mm, Tri-X, Cartier-Bresson style
curl "https://pixsum.dev?prompt=commuters+in+the+rain&preset=street&camera=leica&lens=35mm&film=tri-x&style_ph=cartier-bresson&key=YOUR_STUDIO_KEY"

# Editorial portrait — Hasselblad, 85mm, Portra 400, warm grade
curl "https://pixsum.dev?prompt=chef+plating+a+dish&preset=documentary&camera=hasselblad&lens=85mm&film=portra-400&grade=matte&key=YOUR_STUDIO_KEY"

Custom domain Studio Coming soon#

Serve Pixsum images from your own domain — images.yourbrand.com — via a simple CNAME. No pixsum.dev URLs in your production code.

Caching#

Pixsum uses a two-layer cache. The cache key is a SHA-256 hash of prompt + w + h + style + theme + fmt — identical params always return the same image.

Image consistency in batch#

Pixsum uses a three-layer consistency system to keep characters, lighting, and setting coherent across all images in a batch.

Option A — Prompt anchoring (always on)

When expanding your context brief into individual prompts, the LLM is instructed to extract and lock specific descriptors — exact physical appearance, clothing, location, lighting conditions, camera style — and repeat them verbatim in every prompt. This ensures tonal and stylistic coherence even before any images are generated.

Option B — Visual reference generation (always on)

This is the main consistency driver. Pixsum generates the hero image first, then passes it as a visual input to Gemini when generating each thumbnail. The model literally sees the hero — the characters’ faces, hair, clothing, the lighting, the location — and uses it as a visual anchor.

The thumbnail prompt sent to the model becomes: “Using the people, lighting, and setting in the reference image as a visual anchor, generate: [thumbnail prompt]. Keep the same characters — same faces, hair, clothing. Different moment, same scene.”

This is what makes batch story cards feel like they came from the same shoot rather than independent generations. Visual reference anchoring (Option B) is included in all Batch API plans Growth+.

Formats & sizing#

Supported formats: jpg (default, smaller), webp (better compression for web).

Aspect ratio

Use ar= to set the aspect ratio. When a supported ratio is detected, Pixsum passes it natively to the model — the image is generated at the correct shape rather than being cropped or resized after the fact. This produces better compositions since the model composes for the target frame.

Supported native ratios:

Unsupported ratios (e.g. 2:1) still work — the model generates at its default size and Pixsum resizes to your requested dimensions.

Copy# 16:9 widescreen — generated natively at correct shape
?w=1280&ar=16:9

# Square — no ar needed, 1:1 is inferred from equal w and h
?w=800&h=800

# Let the preset decide — cinematic defaults to 21:9
?prompt=rain+soaked+rooftop&preset=cinematic

# Override preset aspect ratio
?prompt=rain+soaked+rooftop&preset=cinematic&ar=16:9

Resolution tiers

Pixsum automatically selects the best resolution tier based on your requested dimensions. Higher tiers produce sharper images with more detail — the model generates at a higher native resolution before any resizing.