Avatar Generator API: The Complete Guide

Need unique default avatars for your users? This guide covers everything you need to know about generating avatars via API, including identicons, initials, geometric patterns, and implementation examples in multiple languages.

What are Generated Avatars?

Generated avatars are unique images created algorithmically from identifiers like usernames or email addresses. They provide visually distinct default profile pictures for users who haven't uploaded custom photos, helping create a more personalized experience.

A URL like https://api.tinyfn.io/v1/avatar/john@example.com generates a consistent, unique avatar for that email address.

Avatar Styles

The API supports multiple avatar generation styles:

• Identicon: Geometric patterns unique to each identifier (GitHub style)
• Initials: Colored circles with user initials
• Geometric: Abstract geometric shapes
• Pixel: Retro pixel art style
• Robot: Unique robot faces
• Monster: Friendly monster illustrations

Using the Avatar Generator API

TinyFn provides a simple URL-based endpoint to generate avatars:

GET https://api.tinyfn.io/v1/avatar/john@example.com
GET https://api.tinyfn.io/v1/avatar/john@example.com?style=initials&size=200
GET https://api.tinyfn.io/v1/avatar/username?style=identicon&background=007bff

Content-Type: image/png
[Binary image data - unique avatar for the identifier]

Parameters

Code Examples

HTML

<!-- Default identicon avatar -->
<img src="https://api.tinyfn.io/v1/avatar/user@example.com" alt="User Avatar">

<!-- Initials style -->
<img src="https://api.tinyfn.io/v1/avatar/John Doe?style=initials&size=100" alt="JD">

<!-- Geometric style with custom background -->
<img src="https://api.tinyfn.io/v1/avatar/username?style=geometric&background=f0f0f0" alt="Avatar">

JavaScript / React

// Generate avatar URL for user
function getAvatarUrl(identifier, options = {}) {
  const { style = 'identicon', size = 80, background } = options;
  const encoded = encodeURIComponent(identifier);
  let url = `https://api.tinyfn.io/v1/avatar/${encoded}`;

  const params = new URLSearchParams();
  if (style !== 'identicon') params.set('style', style);
  if (size !== 80) params.set('size', size);
  if (background) params.set('background', background);

  return params.toString() ? `${url}?${params}` : url;
}

// React component example
function UserAvatar({ user }) {
  const avatarUrl = user.avatar || getAvatarUrl(user.email, { style: 'initials', size: 100 });
  return <img src={avatarUrl} alt={user.name} className="avatar" />;
}

Python

import urllib.parse

def get_avatar_url(identifier, style='identicon', size=80):
    encoded = urllib.parse.quote(identifier)
    url = f"https://api.tinyfn.io/v1/avatar/{encoded}"
    params = {'style': style, 'size': size}
    query = urllib.parse.urlencode(params)
    return f"{url}?{query}"

# Usage
avatar = get_avatar_url("user@example.com", style="initials", size=200)
print(avatar)

Customization Options

• Size: Generate avatars from 16px to 512px
• Style: Choose from multiple visual styles
• Background: Custom background colors
• Format: PNG for raster, SVG for scalable
• Rounded: Optional rounded corners or circles

Best Practices

1. Use consistent identifiers: Always use the same identifier (email) for a user
2. Provide fallbacks: Use generated avatars as fallback for user photos
3. Cache appropriately: Avatars are deterministic; cache them effectively
4. Size appropriately: Request the size you need to avoid scaling artifacts