Avatune API

The Avatune API provides REST endpoints for generating avatar images on demand at https://avatune.dev.

Live Demo

Try the API right here:

import { createClient } from "@avatune/api-client";

const client = createClient();

const svg = await client.getAvatar({
  theme: "yanliu",
  seed: "user-123",
  size: 200,
});

Live API Endpoints

Format	Endpoint
SVG	`https://www.avatune.dev/api/svg/`
PNG	`https://www.avatune.dev/api/png/`

API Usage

Basic Request

GET https://www.avatune.dev/api/svg/?theme=nevmstas&hair=short

PNG Request

GET https://www.avatune.dev/api/png/?theme=nevmstas&hair=short

Example Response

The API returns an SVG image that can be used directly in <img> tags or embedded in your HTML:

<img src="https://www.avatune.dev/api/svg/?theme=yanliu&seed=user123" alt="Avatar" />

Parameters

Theme

The theme parameter is optional and defaults to yanliu.

Available themes: ashley-seo, ashleyy, cyberpunk, fatin-verse, kyute, micah, miniavs, nevmstas, orks, pacovqzz, pawel-olek-man, pawel-olek-woman, retro-cartoon, yanliu

Optional Parameters

Parameter	Description	Default
`size`	Avatar size in pixels	Theme default
`seed`	Random seed for generation	Random
`backgroundColor`	Background color (hex)	Theme default

Caching

All successful responses include cache headers for optimal performance:

Cache-Control: public, max-age=31536000, immutable

This means:

Responses are cached for 1 year
Content is immutable (won't change)
Can be cached by browsers and CDNs

Use the seed parameter to generate consistent avatars for the same user across requests.

CORS

The API supports Cross-Origin Resource Sharing (CORS), allowing requests from any origin:

Access-Control-Allow-Origin: *

Error Responses

Invalid Theme

{
  "error": "Invalid theme",
  "availableThemes": ["ashley-seo", "..."]
}

Status Code: 400 Bad Request

TypeScript API Client

For type-safe API access, use the official @avatune/api-client package:

npm install @avatune/api-client

Basic Usage

import { createClient } from "@avatune/api-client";

const client = createClient();

// Get avatar SVG with full type safety
const svg = await client.getAvatar({
  theme: "yanliu",
  seed: "user-123",
  hair: "braids", // TypeScript autocompletes available options
  hairColor: "#8B4513",
  body: "sweaterVest",
});

// Get URL for <img> src (no network request)
const url = client.getAvatarUrl({
  theme: "nevmstas",
  seed: "user-456",
  size: 300,
});

Type-Safe Theme Parameters

Each theme has its own typed interface with autocomplete for available parts:

import {
  createClient,
  type YanliuParams,
  type NevmstasParams,
} from "@avatune/api-client";

const client = createClient();

// Yanliu theme with typed parameters
const yanliuAvatar = await client.getAvatar({
  theme: "yanliu",
  hair: "braids", // 'braids' | 'hijab' | 'medium' | 'puff' | ...
  body: "blouse", // 'blouse' | 'sweaterVest' | 'teeBasic' | ...
  glasses: "glass", // optional
});

// Nevmstas theme with different options
const nevmstasAvatar = await client.getAvatar({
  theme: "nevmstas",
  hair: "short", // 'short' | 'long' | 'mohawk' | 'pixie' | ...
  eyes: "boring", // 'boring' | 'dots' | 'round' | ...
});

Error Handling

import { createClient, AvatuneApiError } from "@avatune/api-client";

const client = createClient();

try {
  const svg = await client.getAvatar({ theme: "yanliu", seed: "test" });
} catch (error) {
  if (error instanceof AvatuneApiError) {
    console.log(`API error: ${error.data.error}`);
  }
}

Custom Base URL

For self-hosted instances:

const client = createClient({
  baseUrl: "https://your-api.example.com",
  timeout: 5000,
});

Available Themes

import { AvatuneClient } from "@avatune/api-client";

console.log(AvatuneClient.themes);

Current themes: ashley-seo, ashleyy, cyberpunk, fatin-verse, kyute, micah, miniavs, nevmstas, orks, pacovqzz, pawel-olek-man, pawel-olek-woman, retro-cartoon, yanliu

Integration Examples

HTML Image Tag

<img
  src="https://www.avatune.dev/api/svg/?theme=yanliu&seed=user-123"
  alt="User Avatar"
  width="200"
  height="200"
/>

JavaScript Fetch

const avatarUrl = `https://www.avatune.dev/api/svg/?theme=nevmstas&seed=${userId}&size=300`;
const response = await fetch(avatarUrl);
const svgText = await response.text();

React Component

function UserAvatar({ userId, theme = "yanliu", size = 200 }) {
  const avatarUrl = `https://www.avatune.dev/api/svg/?theme=${theme}&seed=${userId}&size=${size}`;

  return <img src={avatarUrl} alt="Avatar" width={size} height={size} />;
}

Vue Component

<template>
  <img :src="avatarUrl" alt="Avatar" :width="size" :height="size" />
</template>

<script setup>
import { computed } from "vue";

const props = defineProps({
  userId: String,
  theme: { type: String, default: "yanliu" },
  size: { type: Number, default: 200 },
});

const avatarUrl = computed(
  () =>
    `https://www.avatune.dev/api/svg/?theme=${props.theme}&seed=${props.userId}&size=${props.size}`
);
</script>

CSS Background

.avatar {
  width: 200px;
  height: 200px;
  background-image: url("https://www.avatune.dev/api/svg/?theme=miniavs&seed=user-456");
  background-size: cover;
  border-radius: 50%;
}

Infrastructure

The Avatune API is implemented as Next.js route handlers in the website app and deployed with avatune.dev.

Self-Hosting

Run the website app locally:

bun run --cwd apps/website dev

Best Practices

Use Seeds for Consistency: Always use the same seed parameter for a specific user to ensure their avatar remains consistent
Cache Responses: Take advantage of the long cache headers to minimize API calls
URL Encode Parameters: Always URL encode color values and other special characters

Example with URL Encoding

const params = new URLSearchParams({
  theme: "yanliu",
  seed: "user-123",
  hairColor: "#FF5733", // Will be properly encoded
  backgroundColor: "#3498DB",
});

const url = `https://www.avatune.dev/api/svg/?${params}`;

On this page