API Documentation

Complete guide to using PicSUM:DEV's image placeholder API

What is PicSUM:DEV?

PicSUM:DEV is a free, reliable image placeholder service designed specifically for developers. Generate high-quality placeholder images instantly using simple HTTP URLs. No authentication, no API keys, no signup required.

Base URL

BASE URL All API requests start here
https://picsum.dev

No authentication headers required. All endpoints are publicly accessible.

API Endpoints

GET /{width}/{height} Primary

Returns a random placeholder image with specified dimensions.

https://picsum.dev/800/600

Returns an 800×600 pixel image

GET /{width}/{height}?blur={amount} Optional

Applies a blur effect to the image. Amount ranges from 0 (no blur) to 10 (maximum blur).

https://picsum.dev/800/600?blur=5

Returns an 800×600 image with medium blur

GET /{width}/{height}?grayscale=1 Optional

Converts the image to grayscale (black and white).

https://picsum.dev/800/600?grayscale=1

Returns a grayscale 800×600 image

GET /{size} 🆕 NEW

Returns a square image. Provide only one dimension to get a perfect square.

https://picsum.dev/400

Returns a 400×400 square image

https://picsum.dev/1024

Returns a 1024×1024 square image

GET /{width}/{height}?seed={value} 🆕 NEW

Get the same image every time by using a seed parameter. Perfect for consistent avatars, placeholders, and testing.

https://picsum.dev/random/400?seed=123

Always returns the same 400×400 image for seed=123

https://picsum.dev/random/200?seed=user-profile-42

String seeds also work! Great for user avatars.

💡 Pro Tip: Use user IDs or unique identifiers as seeds for consistent, deterministic images.

GET /{width}/{height}?static 🆕 NEW

Get a static image based on dimensions. Each unique size will always return the same image - perfect for consistent layouts and testing.

https://picsum.dev/400/300?static

Always returns the same image for 400×300 dimensions

https://picsum.dev/200/200?static

Different dimensions = different static image

💡 Pro Tip: Use ?static when you want consistent images per size, or ?seed=value when you want the same image across all sizes.

GET /{width}/{height}?blur={amount}&grayscale=1 Advanced

Combine multiple parameters for customized results.

https://picsum.dev/800/600?blur=3&grayscale=1

Returns a blurred, grayscale 800×600 image

Parameters Reference

Parameter Type Required Default Range Description
width integer Required — 1-5000 Image width in pixels
height integer Required — 1-5000 Image height in pixels
blur integer Optional 0 0-10 Blur intensity level
grayscale boolean Optional 0 0 or 1 Convert to grayscale
static flag Optional — — Return same image for same dimensions 🆕 NEW
seed string Optional — any Deterministic image selection for consistent results

Code Examples

HTML
Basic image tag usage
TEXT 
<img src="https://picsum.dev/800/600"
     alt="Placeholder Image"
     loading="lazy" />
JS
Fetch API with async/await
TEXT 
async function loadImage() {
  try {
    const response = await fetch('https://picsum.dev/800/600?blur=2');
    const blob = await response.blob();
    const imageUrl = URL.createObjectURL(blob);

    const img = document.getElementById('placeholder');
    img.src = imageUrl;
  } catch (error) {
    console.error('Failed to load image:', error);
  }
}
React
React component with loading state
TEXT 
import { useState } from 'react';

function PlaceholderImage({ width = 400, height = 300 }) {
  const [loading, setLoading] = useState(true);

  return (
    <img
      src={`https://picsum.dev/${width}/${height}`}
      alt="Placeholder"
      onLoad={() => setLoading(false)}
      className={loading ? 'opacity-50' : 'opacity-100'}
    />
  );
}
CSS
Background image with CSS
TEXT 
.hero-section {
  background-image: url('https://picsum.dev/1920/1080?blur=1');
  background-size: cover;
  background-position: center;
  background-repeat: no-repeat;
}

/* Responsive background */
@media (max-width: 768px) {
  .hero-section {
    background-image: url('https://picsum.dev/800/600?blur=1');
  }
}

Best Practices

Cache Strategically

Implement client-side caching and use CDN for better performance.

Handle Errors Gracefully

Always handle network errors and implement fallbacks.

Use Appropriate Sizes

Request images at the exact size you need to save bandwidth.

Test in Playground

Use our interactive playground to test parameters before implementing.