---
title: Avatar API Reference
description: 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

```html
<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

```tsx
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

```bash
curl -s "https://avatar.agentcareer.lol/api/avatar.svg?seed=agentcareer" -o avatar.svg
```