API Documentation

LazyAvatar API

Generate deterministic PNG avatars from your backend with a simple API request.

1. Create an API key

Create a server API key from your dashboard. The secret is shown once.

Store it as an environment variable on your backend:

LAZYAVATAR_API_KEY=av_live_...

2. Make a request

Send your API key using the x-api-key header.

GET https://api.lazyavatar.com/v1/avatar/doodle?seed=user-123&size=512

x-api-key: av_live_...

The API returns a PNG image.

3. Choose a style

Pass the avatar style in the URL.

doodleanimechibipunkbig-head

4. Use a seed

The seed determines the avatar. The same seed produces the same avatar.

?seed=user-123&size=512

You can use a user ID, username, database ID, or any other stable string as the seed.

5. Keep your API key private

LazyAvatar API keys are server-side credentials.

Keep the key in your server environment.

Send it using the x-api-key header.

Never put it in the URL.

Never expose it to browser JavaScript.

Never include it in client responses or logs.

6. Recommended architecture

Call LazyAvatar from your backend, not directly from the browser.

Browser
   ↓
Your Backend
   ↓  x-api-key
LazyAvatar API
   ↓
PNG
   ↓
Your Backend
   ↓
Browser

Node.js / TypeScript

Example using the built-in fetch API.

const response = await fetch(
  "https://api.lazyavatar.com/v1/avatar/doodle?seed=user-123&size=512",
  {
    headers: {
      "x-api-key": process.env.LAZYAVATAR_API_KEY!,
    },
  }
);

if (!response.ok) {
  throw new Error(
    `LazyAvatar request failed: ${response.status}`
  );
}

const image = await response.arrayBuffer();

// Return image bytes from your backend.

Python

Example using requests.

response = requests.get(
    "https://api.lazyavatar.com/v1/avatar/doodle",
    params={
        "seed": "user-123",
        "size": 512,
    },
    headers={
        "x-api-key": os.environ["LAZYAVATAR_API_KEY"],
    },
    timeout=10,
)

response.raise_for_status()

image = response.content

# Return image bytes from your backend.