Reference

API

One GET endpoint for all 26 avatars, returned at the size and shape you ask for. No API key, no sign-up, and it works from any website or app.

Path form
GET /api/{collection}/{id}/{size}
Query form
GET /api/{collection}?id={id}&size={size}&square=true&fit=full&format=webp
List all avatars
GET /api/photos?collection={collection}

Every part of the path is optional and can go in any order, so /api/gta-vi/raul, /api/gta-vi/raul/240 and /api/gta-vi/240/raul are all valid. If you set the same option in the path and the query string, the query string wins. Anything that is not a collection, an id or a number is treated as a seed — so /api/gta-vi/ada@example.com always returns the same face. Responses carry X-Photo-Collection, X-Photo-Id and X-Photo-Size headers so you can see exactly what you got.

Baelux
baelux
Boobie
boobie
Boobie Ike
boobie-ike

Exact, seeded or random

Every request lands in one of three modes. Use an id when you want a specific image, a seed when each user should keep their own image, and nothing at all when any image will do.

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.

Parameters

collectioncollection namedefault: all

Which collection to draw from. Put it first in the path and the id is looked up inside that collection, so two collections can use the same id. The full list is at GET /api/photos.

/api/gta-vi/jason-mask/160
idimage iddefault: seeded / random

Exact mode: which image to serve. Every id is listed by GET /api/photos and under each image in the gallery. An unknown id returns 404, unless you also pass a seed, in which case the seed is used instead. An id on its own works as long as only one collection has it; otherwise you get a 409 listing the collections to choose from.

/api/gta-vi/jason-mask/160
seedany stringdefault: random

Turn any string — an email, a username, a user id — into an avatar. The same string always gets the same image, and it never returns 404. name= works too. /api/{collection}/seed/{anything} uses the rest of the path as-is, so a seed that looks like an id or a number is still treated as a seed. With no seed and no id you get a random image each time. The X-Photo-Match header tells you which one was used: id, seed or random.

/api/gta-vi?seed=ada@example.com&size=96
size8–2160default: 80

Width and height in pixels. Images are never enlarged beyond their original size; the actual size you got is in the X-Photo-Size header.

/api/roxy/256
fitcover | fulldefault: cover

cover crops the centre of the image to a square. full keeps the original aspect ratio and uses size as the longest edge — handy for wallpapers. full images are never cut to a circle.

/api/gta-vi/boobie-ike/1200?fit=full
squarebooleandefault: false

Return a square instead of a circle.

/api/raul/200?square=true
formatwebp | png | jpegdefault: webp

WebP by default: it supports the transparent corners a circle needs and is much smaller than PNG. Use png or jpeg if you need them. JPEG has no transparency, so a circular JPEG gets its corners filled with the bg colour.

/api/gta-vi/cal/240?format=png
bghexdefault: ffffff

Corner colour for circular avatars requested as JPEG.

/api/gta-vi/cal/240?format=jpeg&bg=0b0b14

Ids

Every avatar you can request, grouped by collection. Use them as /api/<collection>/<id>, or fetch the same list as JSON from GET /api/photos.

gta-vi26 images

baelux boobie boobie-ike brian brian-heder cal cal-hampton drequan drequan-priest jason-and-lucia-01 jason-and-lucia-02 jason-and-lucia-beach jason-and-lucia-lock-and-load jason-and-lucia-robbery jason-and-lucia-rooftop jason-car jason-lucia-motel jason-mask lucia-car lucia-mask official-cover-art raul raul-bautista real-dimez roxy the-album-cover-art

Caching & limits