API Documentation
Start integrating with our powerful and simple API to get beautiful placeholder images for your projects
Basic Usage
Our simple API endpoints to get placeholder images for your projects
| Endpoint | Description | Example |
|---|---|---|
| /width/height | Get a random image with specific dimensions | https://picsum.dev//300/200 |
| /size | Get a square image by providing just one dimension | https://picsum.dev//400 |
| /static/seed | Get the same image every time for a specific seed | https://picsum.dev//static/123 |
| /static/seed/width/height | Get the same image every time with specific dimensions | https://picsum.dev//static/123/300/200 |
| /image/id/view | Get a specific image by its ID | https://picsum.dev//image/1/view |
| /meta/id | Get image metadata in JSON format | https://picsum.dev//meta/1 |
Code Examples
How to implement our API in your projects
HTML Example
Simple Integration<img src="https://picsum.dev//300/200" alt="Random Image">
<img src="https://picsum.dev//image/1/view" alt="Specific Image">
<img src="https://picsum.dev//static/42/300/200" alt="Static Image">CSS Example
Background Images.header-bg {
background-image: url(https://picsum.dev//1200/400);
background-size: cover;
}
.avatar {
background-image: url(https://picsum.dev//static/123/200);
background-size: cover;
width: 200px;
height: 200px;
border-radius: 50%;
}JavaScript Example
API Integration// Fetch image metadata
fetch('https://picsum.dev//meta/1')
.then(response => response.json())
.then(data => console.log(data));
// Generate profile images for users with consistent images per user
function getUserAvatar(userId, size = 200) {
return 'https://picsum.dev//static/' + userId + '/' + size;
}Rate Limits and Caching
Important information about service usage
Rate Limits
To ensure service availability, we apply rate limiting of 60 requests per minute per IP address. If you exceed this limit, you will receive a 429 (Too Many Requests) response.
Caching
Our images are cached for 1 week. We recommend you also cache the images on your side when possible to reduce bandwidth usage and improve performance.
Static Images
Static images will always return the same image for the same seed, making them ideal for user avatars or consistent placeholder images. The seed can be any number and is used to deterministically select an image from our library.
Need help with integration?
Our team is ready to assist you with any questions