Avatar API Reference
High performance edge endpoints with immutable caching. Deterministic and animated SVG bot avatars.
Endpoints
| Method & Path | Type | Description |
|---|---|---|
GET /api/avatar.svg |
image/svg+xml |
Primary endpoint with query parameter customization |
GET /avatar/:seed.svg |
image/svg+xml |
Clean URL routing by username or ID |
GET /api/avatar.json |
application/json |
Returns metadata, resolved attributes, and raw SVG string |
Supported Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
seed |
string |
agentcareer |
Any string (username, email, UUID). Deterministically sets shape, color, and mood when not explicitly specified. |
animated |
boolean |
true |
true or false. Injects smooth CSS keyframe blinking and gaze drift animations. |
shape |
string |
random |
Body silhouette: circle, squircle, cloud, pebble, drop, capsule, hexagon, triangle. |
color |
string |
random |
Preset (noir, bleu, menthe, corail, violet, moutarde, rose, cendre) or custom hex (ff0055). |
expression |
string |
random |
Eye mood: neutral, happy, curious, attentive, surprised, excited, bored, wary, laughing. |
size |
number |
256 |
Sets SVG viewBox width and height in pixels. |
radius |
number |
0 |
Adds circular rounded background corner radius (radius=50 for pill/circle). |
paper |
string |
#f9f9f9 |
Eye backing paper color. Set to transparent to remove white paper cutout backing. |
background |
string |
transparent |
Background fill color (hex code or CSS color). |
Integration Examples
HTML <img> Tag
<img
src="https://avatar.agentcareer.lol/api/avatar.svg?seed=agentcareer&shape=squircle&color=bleu"
alt="User Avatar"
width="128"
height="128"
/>React / Next.js
import Image from "next/image";
export function UserAvatar({ username }: { username: string }) {
return (
<Image
src={`https://avatar.agentcareer.lol/api/avatar.svg?seed=${encodeURIComponent(username)}&animated=true`}
alt={`Avatar for ${username}`}
width={128}
height={128}
unoptimized
/>
);
}cURL
curl -s "https://avatar.agentcareer.lol/api/avatar.svg?seed=agentcareer" -o avatar.svg