API Documentation

Everything you need to integrate LoremFaces placeholder avatars into your project.

Quick Start

LoremFaces provides five AI-generated placeholder avatars via simple URLs. No API key or signup is required. Choose a stable face ID from 1–5, or select one client-side when you want variety.

<!-- Basic usage -->
<img src="https://www.loremfaces.net/96/id/1.jpg" alt="User avatar">

<!-- Random face on each page load: pick a random ID (1-5) -->
<img id="avatar" alt="Random avatar">
<script>
  avatar.src = `https://www.loremfaces.net/96/id/${1 + Math.floor(Math.random() * 5)}.jpg`;
</script>

Try it live

URL Pattern

New integrations should use the stable ID-based path:

Legacy compatibility: existing /{size}/random.jpg links resolve to a fixed fallback image. They do not rotate. New integrations should select an ID from 1–5 in application code.

Parameters

Size

Available image sizes (square dimensions in pixels):

Face ID

IDs range from 1 to 5. Each ID returns the same face consistently across all sizes.

// Same person, different sizes
https://www.loremfaces.net/24/id/1.jpg  // 24x24
https://www.loremfaces.net/96/id/1.jpg  // 96x96
https://www.loremfaces.net/256/id/1.jpg // 256x256

Code Examples

HTML

<!-- Avatar list -->
<div class="avatar-list">
  <img src="https://www.loremfaces.net/48/id/1.jpg" alt="User 1">
  <img src="https://www.loremfaces.net/48/id/2.jpg" alt="User 2">
  <img src="https://www.loremfaces.net/48/id/3.jpg" alt="User 3">
</div>

CSS Background

.user-avatar {
  width: 96px;
  height: 96px;
  border-radius: 50%;
  background-image: url('https://www.loremfaces.net/96/id/1.jpg');
  background-size: cover;
}

JavaScript

// Generate avatar URL
function getAvatarUrl(size, id) {
  return `https://www.loremfaces.net/${size}/id/${id}.jpg`;
}

// Random avatar URL (picks a random ID 1-5)
function getRandomAvatarUrl(size) {
  return getAvatarUrl(size, 1 + Math.floor(Math.random() * 5));
}

// Usage
const avatar = getAvatarUrl(96, 1);
console.log(avatar); // https://www.loremfaces.net/96/id/1.jpg

Markdown

![User Avatar](https://www.loremfaces.net/96/id/1.jpg)

Best Practices

Use Consistent IDs

For prototypes where the same user appears multiple times, always use the same face ID to maintain consistency.

Choose Appropriate Sizes

Use the smallest size that looks good at your display dimensions. This reduces bandwidth and improves load times.

Add Alt Text

Always include descriptive alt text for accessibility:

<img src="https://www.loremfaces.net/96/id/1.jpg"
     alt="Placeholder avatar for John Doe">

Framework Guides

Detailed integration guides for popular frameworks:

• React Integration Guide
• Vue 3 Integration Guide
• Next.js Integration Guide
• Svelte Integration Guide
• Angular Integration Guide
• Astro Integration Guide

Compare with Alternatives

See how LoremFaces compares to other placeholder avatar services:

View Comparison →