Lorem Picsum Getting Started: Quick Image Placeholders (2026)

Getting started overview

Getting started with Lorem Picsum involves making direct HTTP GET requests to its API endpoints. Unlike many APIs, Lorem Picsum does not require an account, API keys, or any form of authentication to retrieve images. This design simplifies its use for development and prototyping. The primary method of interaction is through constructing specific URLs that define the desired image attributes, such as dimensions, whether it should be grayscale, or if a specific image ID is requested. Image data is returned directly as the response body for valid requests.

The workflow for obtaining placeholder images generally follows these steps:

1. Identify the desired image parameters (e.g., width, height, grayscale).
2. Construct the appropriate URL based on the Lorem Picsum API documentation.
3. Make an HTTP GET request to the constructed URL.
4. Receive the image data in response.

This streamlined approach is suitable for developers who need quick, unauthenticated access to a large library of diverse placeholder images for various web and application development tasks. Developers commonly use command-line tools like curl or browser-based requests to test and integrate Lorem Picsum images into their projects.

Here's a quick reference for the getting started process:

Create an account and get keys

Lorem Picsum operates without requiring users to create an account or obtain API keys. This is a core feature of its design, aimed at providing immediate and unrestricted access to its image library for development purposes. Therefore, there is no signup process, dashboard, or credential management associated with using Lorem Picsum.

The absence of authentication simplifies integration significantly. Developers do not need to manage API keys, handle authentication tokens, or implement complex authorization flows. This makes Lorem Picsum particularly useful for rapid prototyping, quick mockups, and scenarios where a simple, publicly accessible image source is sufficient. The API's operational model focuses on direct URL-based requests for image retrieval, as detailed in the Lorem Picsum documentation.

For services that do require API keys, the process typically involves:

1. Registering on the provider's website.
2. Navigating to a developer dashboard or API settings section.
3. Generating a new API key or secret.
4. Storing these credentials securely for use in API requests.

However, none of these steps apply to Lorem Picsum, as it explicitly avoids such requirements. Developers can proceed directly to making requests after understanding the available URL parameters.

Your first request

Making your first request to Lorem Picsum is straightforward due to the lack of authentication. You can retrieve a random image by specifying its width and height in the URL. For instance, to get a random image that is 200 pixels wide and 300 pixels tall, you would use the following URL:

GET https://picsum.photos/200/300

You can test this request directly in a web browser by navigating to https://picsum.photos/200/300, or using a command-line tool like curl:

curl -o random_image.jpg https://picsum.photos/200/300

This command downloads a random 200x300 pixel image and saves it as random_image.jpg. The API provides several options for customizing image requests:

• Specific Dimensions: https://picsum.photos/{width}/{height} (e.g., https://picsum.photos/400/250 for a 400x250 pixel image).
• Square Image: https://picsum.photos/{size} (e.g., https://picsum.photos/300 for a 300x300 pixel image).
• Grayscale: Add ?grayscale to the URL (e.g., https://picsum.photos/200/300?grayscale).
• Blur: Add ?blur to the URL, optionally with a radius from 1 to 10 (e.g., https://picsum.photos/200/300?blur or https://picsum.photos/200/300?blur=5).
• Specific Image ID: Use https://picsum.photos/id/{image_id}/{width}/{height} (e.g., https://picsum.photos/id/237/200/300 for image ID 237).
• List of Images: https://picsum.photos/v2/list returns a JSON array of image metadata, including IDs. This can be paginated using ?page={page_number}&limit={items_per_page}.

For example, to retrieve image with ID 35, in grayscale, with dimensions 500x300 pixels:

GET https://picsum.photos/id/35/500/300?grayscale

You can embed these URLs directly into HTML <img> tags:

<img src="https://picsum.photos/200/300" alt="Random placeholder image">
<img src="https://picsum.photos/id/10/400/200?grayscale&blur=2" alt="Specific grayscale blurred image">

This demonstrates the simplicity and directness of Lorem Picsum's API for immediate image retrieval.

Common next steps

After successfully making your first request to Lorem Picsum, developers commonly explore additional features and integration methods. These steps often include:

1. Exploring Advanced Parameters: Experiment with different URL parameters such as ?grayscale, ?blur, and specific image IDs (/id/{id}) to customize the placeholder images further. The Lorem Picsum documentation provides a complete list of available parameters and their usage.

2. Integrating into Web Applications: Incorporate Lorem Picsum images directly into HTML or CSS for web development. This might involve dynamically generating image URLs in JavaScript for single-page applications or using them as placeholders during development in frameworks like React, Angular, or Vue.js. For instance, an <img> tag can directly reference a Lorem Picsum URL.

3. Using the List API: For more control, fetch a list of available image metadata using the /v2/list endpoint. This allows developers to programmatically select image IDs, apply pagination, and retrieve author information. An example request would be https://picsum.photos/v2/list?page=2&limit=10, which fetches 10 images from the second page of results.

4. Performance Considerations: While Lorem Picsum is designed for convenience, it is important to consider image loading performance in production environments. For production, optimizing images (compression, lazy loading, responsive images) is typically necessary. Tools like Google PageSpeed Insights often recommend specific image optimization techniques to improve web performance.

5. Testing and Mocking: Utilize Lorem Picsum for UI/UX testing and development. Its reliable availability and simple API make it an effective tool for populating layouts with visual content without needing to manage a local image library or mock data. This is particularly useful for ensuring design consistency and responsiveness across various screen sizes and resolutions.

6. Comparing Alternatives: While Lorem Picsum is excellent for basic placeholder needs, you might explore alternatives like Unsplash or Pexels if your project requires advanced features such as image search, higher resolution images, or specific content categories. However, these often involve API keys and more complex integration.

These next steps help transition from a basic image request to more integrated and robust usage of placeholder images in development workflows.

Troubleshooting the first call

Troubleshooting issues with your first Lorem Picsum API call is generally straightforward due to its simplicity. Most problems stem from incorrect URL formatting or network connectivity. Here are common issues and their solutions:

1. Image Not Loading or Showing Broken Image Icon

• Issue: The browser or application displays a broken image icon.

  Solution: Double-check the URL for typos. Ensure the width and height values are numeric and correctly placed. For example, https://picsum.photos/200/300 is correct, while https://picsum.photos/width=200&height=300 is incorrect for the base image endpoint. Refer to the Lorem Picsum API documentation for correct URL structures.

2. Receiving a 404 Not Found Error

• Issue: The server responds with an HTTP 404 status code.

  Solution: This usually means the resource at the specified URL does not exist. If you're using a specific image ID (e.g., https://picsum.photos/id/99999/200/300), the ID might be out of range. Try a common ID (like 237) or remove the ID part of the URL to get a random image. Also, verify that the /id/ segment is correctly placed if you're attempting to fetch a specific image by ID.

3. Network Connection Issues

• Issue: The request times out or fails due to network problems.

  Solution: Ensure your device has an active internet connection. If you are behind a corporate firewall or proxy, it might be blocking access to external image sources. Test with a simple request like curl google.com to confirm general internet connectivity. If using curl, ensure you are not experiencing DNS resolution issues, which could be checked by trying to ping the domain directly (e.g., ping picsum.photos).

4. Image Parameters Not Applying (e.g., Grayscale or Blur)

• Issue: Parameters like ?grayscale or ?blur do not seem to affect the image.

  Solution: Ensure the query parameters are correctly formatted with a question mark (?) for the first parameter and ampersands (&) for subsequent parameters. For example, https://picsum.photos/200/300?grayscale&blur=5 is correct. Incorrect syntax like https://picsum.photos/200/300?grayscale?blur=5 will not work. Also, clear your browser cache, as browsers might sometimes cache previous versions of images without the applied effects.

5. Unexpected Image Content

• Issue: The image returned is not what was expected (e.g., an error page from a proxy).

  Solution: This can occur if a proxy server or content filter intercepts the request. Check your network settings and any browser extensions that might interfere with HTTP requests. Sometimes, a VPN might route traffic through a blocked server. Temporarily disabling such tools can help diagnose if they are the cause. For programmatic requests, examine the full HTTP response headers and body to see if any intermediary server is injecting content.

By systematically checking these points, most initial Lorem Picsum request issues can be quickly resolved.