26 avatars · free · no key

Avatars for your app,
from a single URL

Drop a URL into an <img> tag and get a ready-to-use avatar at any size — as a circle, a square or the full image. Pick one by name, or pass a username and get the same face back every time.

Baelux
Shape
160px
GET /api/gta-vi/baelux/160
What’s available

Collections

Avatars are grouped into collections. Put a collection name in the URL to keep random or username-based picks inside that set.

BaeluxBoobieBoobie IkeBrian

gta-vi26 images

Use /api/gta-vi to pick from this set — as a circle, a square or the full image.

Exact or random

Pick it, pin it, or roll it

Name an id to get that exact image. Pass a seed to give each user their own image that never changes. Leave both out for a random one.

ExactX-Photo-Match: id

You choose the image

Pass a collection and an id.

/api/gta-vi/baelux/96
  • Always the same image, for everyone.
  • Unknown id → 404 (or falls back to seed if you pass one).
  • Cached for a year.
SeededX-Photo-Match: seed

Same image per user

Pass any string as seed= (email, username, uuid).

/api/gta-vi?seed=ada@example.com&size=96
  • You don't pick the image — the seed does.
  • Same seed → same image, every time. Never 404s.
  • Cached for a year.
RandomX-Photo-Match: random

A new image each request

Pass no id and no seed, or add /random.

/api/gta-vi/random/96
  • Different image on every load.
  • Not cached (Cache-Control: no-store).
  • /random ignores a seed, but an id still wins.

Priority: id → seed → random. Every response says which one was used in the X-Photo-Match header.

How to use it

One URL. That’s the API.

Every part of the URL is optional and can go in any order, so /api/gta-vi/raul and /api/gta-vi/240/raul both work. Exact and seeded URLs always return the same image, so browsers cache them and pages stay fast; random ones never cache.

BaeluxBoobieBoobie Ike
HTML
<img src="/api/gta-vi/baelux/120" alt="" width="120" height="120" />
Same avatar per user
<img src="/api/gta-vi?seed=ada@example.com&size=120" alt="" width="120" height="120" />
Download with curl
curl "https://your-host/api/gta-vi/baelux/512?square=true" -o avatar.webp
npm package

Prefer a client? Install veyce.

The veyce package builds these URLs for you, with types. It has zero dependencies, is about 2 KB gzipped, and runs in the browser, Node 18+, Bun, Deno and edge runtimes. It also includes a React <Avatar> component and a CLI.

Install
npm install veyce
JavaScript / TypeScript
import { createAvatars } from "veyce";

const avatars = createAvatars({
  defaults: { collection: "gta-vi", size: 96 },
});

avatars.url({ seed: "ada@example.com" });
React
import { Avatar } from "veyce/react";

<Avatar seed="ada@example.com" size={48} />

Pick any face

Every image has a short, readable id. Ask for it by collection and id and you get exactly that image, every time.

Cropped on the way out

A circle by default, square=true for square corners, or fit=full for the whole image at its original aspect ratio.

No key, no CORS wall

No API key, no sign-up, and it works from any site. Point an <img> at a URL and you're done.

Stable per user

Pass a username or email as seed= and the same person always gets the same avatar — nothing to store on your side.