Documentation

Avadun is a high-performance, privacy-focused avatar generation API. It creates beautiful, deterministic avatars from names without requiring user uploads or third-party dependencies.

Lightning Fast

Optimized caching and CDN delivery for instant load times.

No API Key

Start using immediately without registration.

Deterministic

Same name always generates the same avatar.

Pro Tip: All avatars are cached for 30 days with ETag support. The API automatically generates consistent colors based on the name parameter.

Quick Start

Get started in seconds. Just make a GET request to our endpoint with a name parameter.

Basic Usage

The simplest way to use Avadun. Just provide a name.

size=64 (default)

Circular & Resized

Add rounded=true for a circle and size to scale.

size=128, rounded=true

HTML Implementation

<img 
  src="https://avadun.com/api/avatar?name=Alice+Johnson&size=64&rounded=true" 
  alt="Alice Johnson" 
  class="w-16 h-16 rounded-full" 
/>

Parameters

Customize your avatars with these query parameters. Only name is required.

Essential

Name	Type	Default	Description
name	string	Required	The full name to generate initials from.
size	integer	64	Image size in pixels (16-512).
rounded	boolean	false	Render as a circle.

Styling

Name	Type	Default	Description
background	hex	auto	Background color (e.g., "FF0000").
color	hex	FFFFFF	Text color (e.g., "000000").
font	string	inter	Font family: `inter`, `manrope`, `ptserif`, `notosans`, `karla`
bold	boolean	false	Use bold font weight.

Examples

Basic

?name=Alice+Johnson

Circular

?rounded=true

Custom Colors

?background=4F46E5

Bold Text

?bold=true

Single Letter

?name=Grace

Dark Theme

?background=18181B

Error Handling

Avadun is designed to be resilient. It prioritizes returning a usable image over throwing errors.

Graceful Fallbacks

Missing Name
Returns an avatar with "?" initials.
Invalid Size
Clamped to nearest valid size (16-512px).
Invalid Color
Falls back to auto-generated color.

Status Codes

200 Success

Avatar generated

429 Too Many Requests

Rate limit exceeded

500 Server Error

Something went wrong

Rate Limits

Guest

Public

300

requests per minute

Authenticated

Pro

1000

requests per minute

FAQ

Do I need an API key?

No, the basic API is completely free to use without registration.

How are colors generated?

Colors are deterministically generated from the name hash. Same name = same color.

Commercial use?

Yes, free for commercial use within rate limits.

Non-Latin names?

Fully supported. We extract initials from any character set.