#Avatar API

A free endpoint that turns any string into a character. Put the URL in an <img> and you get a deterministic Aora Bot avatar: the same id always returns the same character, with nothing to install, store or sign up for.

#Use it

<img src="https://aora-bot.vercel.app/avatar/alice.svg" width="64" height="64" alt="alice" />

In Markdown, which works in a README, an issue or a comment on any host that allows remote images:

![alice](https://aora-bot.vercel.app/avatar/alice.svg)

The id is any URL-safe string up to 128 characters: a username, an email hash, a database key. The .svg suffix is optional.

#Parameters

Every parameter is optional and goes in the query string.

Variants by style:

• vector: solid (default), outline, glass, sticker, paper, soft, riso
• pixel: crisp (default), dot, block
• kaomoji: plain (default), bubble

Every parameter of the chosen style is also a query key, for example strokeWidth or paperOffset for vector, grid or outline for pixel, weight or tail for kaomoji. Numbers are written as numbers and booleans as true or false (1 and 0 also work). The ranges are listed on the style pages: vector, pixel and kaomoji.

https://aora-bot.vercel.app/avatar/alice.svg?style=pixel&variant=block&size=96
https://aora-bot.vercel.app/avatar/alice.svg?state=happy
https://aora-bot.vercel.app/avatar/mochi-blue.svg?shape=mochi&color=blue&state=happy
https://aora-bot.vercel.app/avatar/alice.svg?variant=paper&paperOffset=12

The console on the home page builds one of these for you: choose the avatar format on its code chip to copy the link for the character you made.

A value outside these lists, such as style=oil, color=plaid, size=big or a style parameter out of range, returns HTTP 400 with a one-line plain-text reason. Query parameters the endpoint does not know are ignored. The background is transparent.

#Which character you get

If the id is exactly a cast id, you get that character: /avatar/luna.svg is Luna. Any other id is hashed to one of the 46 cast members, so the choice is stable and spreads evenly. shape, color and face replace what the id picked, so an id with all three set is only a file name. Because the cast has 46 members, two different ids can land on the same character; treat the avatar as a friendly default, not as a unique identity.

The result is fixed for a given engine version. A release that redraws a character or changes the cast can change what an id looks like.

#Caching and embedding

Responses are image/svg+xml with Cache-Control: public, max-age=86400, s-maxage=31536000, stale-while-revalidate=604800, so a browser keeps an avatar for a day and the edge for a year. The endpoint sends Access-Control-Allow-Origin: *, so you can also fetch it from any origin. The SVG is standalone: no script, no external references.

Inside an <img> the SVG cannot see your page, so the ink of some characters follows the viewer's system light or dark setting rather than your site's theme.

#In an app, render locally

For a product, render avatars yourself rather than calling an endpoint on every page view. The server-safe entry needs no DOM and no network:

import { castMember, renderStaticSvg } from '@aora-bot/engine/static';

const luna = castMember('luna')!;
const svg = renderStaticSvg({ shape: luna.shape, color: luna.color, state: 'happy', sizePx: 64 });

renderAvatarDataUrl(key) does the same for an arbitrary key in one line. It picks from the engine's own pool, so it does not return the characters this endpoint picks for the same id. See Server rendering for the details.