# Avatar API
> Generate deterministic avatars and identicons from any seed — the same seed always renders the exact same avatar, so user IDs, usernames or emails map to stable, unique profile pictures with no storage. 30 art styles (bottts robots, pixel-art, avataaars, identicon, lorelei, notionists, fun-emoji, shapes, rings and more), returned as ready-to-use SVG markup or a base64 PNG data-URI, with options for size, corner radius, background colour and flip. Backed by DiceBear. Ideal for default user avatars, comment/forum placeholders, dashboards, game characters, test fixtures and any UI that needs an instant, reproducible profile image.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/avatar-api/..."
```

## Pricing
- **Free** (Free) — 10,000 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 150,000 calls/Mo, 8 req/s
- **Pro** ($11/Mo) — 750,000 calls/Mo, 20 req/s
- **Mega** ($33/Mo) — 3,000,000 calls/Mo, 50 req/s

## Endpoints

### Avatars

#### `GET /v1/avatar` — Generate an avatar from a style + seed

**Parameters:**
- `style` (query, optional, string) — Avatar style (see /v1/styles), e.g. bottts, pixel-art, identicon Example: `bottts`
- `seed` (query, required, string) — Any seed — user id, username, email; same seed = same avatar Example: `oanor`
- `format` (query, optional, string) — svg (markup) or png (base64 data-URI), default svg Example: `svg`
- `size` (query, optional, string) — Pixel size 16-512 Example: `128`
- `background` (query, optional, string) — 6-digit hex background colour, e.g. b6e3f4
- `radius` (query, optional, string) — Corner radius 0-50

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/avatar-api/v1/avatar?style=bottts&seed=oanor&format=svg&size=128"
```

**Response:**
```json
{
    "data": {
        "avatar": {
            "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 180 180\" fill=\"none\" shape-rendering=\"auto\" width=\"128\" height=\"128\"><metadata xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\" xmlns:dcterms=\"http://purl.org/dc/terms/\"><rdf:RDF><rdf:Description><dc:title>Bottts</dc:title><dc:creator>Pablo Stanley</dc:creator><dc:source xsi:type=\"dcterms:URI\">https://bottts.com/</dc:source><dcterms:license xsi:type=\"dcterms:URI\">https://bottts.com/</dcterms:license><dc:rights>Remix of „Bottts” (https://bottts.com/) by „Pablo Stanley”, licensed under „Free for personal and commercial use” (https://bottts.com/)</dc:rights></rdf:Description></rdf:RDF></metadata><mask id=\"viewboxMask\"><rect width=\"180\" height=\"180\" rx=\"0\" ry=\"0\" x=\"0\" y=\"0\" fill=\"#fff\" /></mask><g mask=\"url(#viewboxMask)\"><g transform=\"translate(0 66)\"><g opacity=\".9\" stroke=\"#2A3544\"><ellipse cx=\"32.5\" cy=\"23\" rx=\"16.5\" ry=\"18\" stroke-width=\"6\"/><path d=\"M29.51 36.76c-7.4 4.29-17 1.55-21.42-6.1\" stroke-width=\"4\"/><ellipse cx=\"28.5\" cy=\"52.5\" rx=\"16.5\" ry=\"14.5\" stroke-width=\"4\"/></g><g opacity=\".9\" stroke=\"#2A3544\"><path d=\"M168.6 60.42c-4.27-7.41-13.95-9.84-21.6-5.42\" stroke-width=\"4\"/><ellipse cx=\"148.5\" cy=\"22.5\" rx=\"16.5\" ry=\"15.5\" stroke-width=\"6\"/></g><mask id=\
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/random` — An avatar whose style is derived from the seed

**Parameters:**
- `seed` (query, required, string) — Any seed, e.g. user-42 Example: `user-42`
- `format` (query, optional, string) — svg or png (default svg) Example: `svg`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/avatar-api/v1/random?seed=user-42&format=svg"
```

**Response:**
```json
{
    "data": {
        "avatar": {
            "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 762 762\" fill=\"none\" shape-rendering=\"auto\"><metadata xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\" xmlns:dcterms=\"http://purl.org/dc/terms/\"><rdf:RDF><rdf:Description><dc:title>Adventurer</dc:title><dc:creator>Lisa Wischofsky</dc:creator><dc:source xsi:type=\"dcterms:URI\">https://www.figma.com/community/file/1184595184137881796</dc:source><dcterms:license xsi:type=\"dcterms:URI\">https://creativecommons.org/licenses/by/4.0/</dcterms:license><dc:rights>Remix of „Adventurer” (https://www.figma.com/community/file/1184595184137881796) by „Lisa Wischofsky”, licensed under „CC BY 4.0” (https://creativecommons.org/licenses/by/4.0/)</dc:rights></rdf:Description></rdf:RDF></metadata><mask id=\"viewboxMask\"><rect width=\"762\" height=\"762\" rx=\"0\" ry=\"0\" x=\"0\" y=\"0\" fill=\"#fff\" /></mask><g mask=\"url(#viewboxMask)\"><path d=\"M396 164.8a224.8 224.8 0 0 1 104.8 42.4c6.2 4.9 12.5 9.4 18 15a225.4 225.4 0 0 1 71.8 149 58.5 58.5 0 0 1 50.9 42.2 71 71 0 0 1-27.6 76.5c-11 7.7-24.5 12-38 11.7-5 0-10-1.6-15-1.8-1.9 2.2-3.3 4.9-4.8 7.3A223.3 223.3 0 0 1 389 609.8c-11 .7-21.9 2-33 .7a223.7 223.7 0 0 1-178.8-342.3A223.4 223.4 0 0 1 352 163.5c14.6-1.4 29.4-.3 44 1.3Z\" fill=\"#000\"/><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M498.8 
…(truncated, see openapi.json for full schema)
```

### Reference

#### `GET /v1/styles` — Every available avatar style

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/avatar-api/v1/styles"
```

**Response:**
```json
{
    "data": {
        "note": "Pass style + seed to /v1/avatar. The same seed always renders the same avatar.",
        "count": 30,
        "styles": [
            "adventurer",
            "adventurer-neutral",
            "avataaars",
            "avataaars-neutral",
            "big-ears",
            "big-ears-neutral",
            "big-smile",
            "bottts",
            "bottts-neutral",
            "croodles",
            "croodles-neutral",
            "dylan",
            "fun-emoji",
            "glass",
            "icons",
            "identicon",
            "initials",
            "lorelei",
            "lorelei-neutral",
            "micah",
            "miniavs",
            "notionists",
            "notionists-neutral",
            "open-peeps",
            "personas",
            "pixel-art",
            "pixel-art-neutral",
            "rings",
            "shapes",
            "thumbs"
        ],
        "formats": [
            "svg",
            "png"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:40.137Z",
        "request_id": "49707fc7-2616-4258-86ba-fda8768abd4c"
    },
    "status": "ok",
    "message": "Styles retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Source & usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/avatar-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Deterministic avatars. /v1/avatar = an avatar from style + seed (format=svg returns the SVG markup, format=png returns a base64 data URI; options: size 16-512, radius 0-50, background hex, flip); /v1/random = an avatar whose style is derived from the seed; /v1/styles = all 30 styles. The same seed always yields the same avatar — perfect for user/profile placeholders.",
        "source": "DiceBear (api.dicebear.com, v9.x)",
        "endpoints": [
            "/v1/avatar",
            "/v1/random",
            "/v1/styles",
            "/v1/meta"
        ],
        "styles_count": 30
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:40.184Z",
        "request_id": "9255dd3f-5ec6-4ad5-8604-afef3d89cb52"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/avatar-api
OpenAPI spec: https://www.oanor.com/api/avatar-api/openapi.json