Minecraft avatar API

Render any player’s face as a PNG from one URL. Any size, with or without the hat layer, by UUID or username, no API key.

What an avatar is

A Minecraft avatar is the front of the player’s head: the 8×8 pixel face from the skin texture with the 8×8 hat layer composited on top, exactly as the game shows it in a player list. Skin Render returns it as a PNG with a transparent background, scaled with nearest-neighbour sampling so every texture pixel stays a crisp square rather than a blurry blob. It is the cheapest render type to produce and to serve, which makes it the right choice for anything you show hundreds of at once: member lists, comment threads, leaderboards, chat.

<img src="https://skinrender.dev/render/069a79f444e94726a5befca90e38aaf5/face?size=64"
     width="64" height="64" alt="Notch" loading="lazy" decoding="async">

Add width and height attributes matching the requested size so the layout does not shift, and loading="lazy" for lists. If you scale the image up in CSS, set image-rendering: pixelated so the browser does not smooth it.

UUIDs versus usernames

Both work in the URL, but they behave differently. A UUID (069a79f444e94726a5befca90e38aaf5, with or without dashes) identifies a Minecraft account forever. A username (Notch) identifies the account that currently holds that name; players can rename every 30 days and a dropped name can be taken by someone else after a cooling-off period. If you store a URL in a database, a forum post or a Discord message, store the UUID form: it will still point at the same person in five years.

Usernames are also one lookup slower the first time. Skin Render has to ask Mojang which UUID the name belongs to before it can fetch the skin, and Mojang rate-limits those lookups; the name-to-UUID answer is cached for an hour (the profile behind it for 15 minutes), so only the very first request pays. If you already have the UUID from a server plugin, a login flow or the /api/profile/ endpoint, use it.

https://skinrender.dev/render/jeb_/face?size=64
https://skinrender.dev/render/853c80ef3c3749fdaa49938b674adae6/face?size=64
https://skinrender.dev/render/853c80ef-3c37-49fd-aa49-938b674adae6/face?size=64

All three produce the same image today; only the last two are guaranteed to do so next year.

The hat layer

Modern skins have a second 8×8 layer over the head, used for hair, hats, glasses, helmets and the like. It is drawn by default. hat=false (alias helmet=false) hides it, which some sites prefer for a uniform, flat look, and overlay=false hides every second-layer part at once. Because the hat layer is often partly transparent, disabling it can reveal a rather different face; test with the players you actually display.

Sizes and backgrounds

The face is square, so size sets both dimensions. Anything from 8 to 1024 is allowed. Sizes that are multiples of 8 scale every texture pixel by the same integer factor (64 px is 8×, 128 px is 16×); other sizes still render crisply but some texture pixels end up one screen pixel wider than others. For retina screens request twice the CSS size you display, e.g. size=128 for a 64 px avatar.

bg=1e1e2e fills the transparent background with a colour (3, 4, 6 or 8 hex digits). mirror=true flips the face, which is occasionally useful for facing an avatar toward text. There is no rounded-corner option; do that in CSS with border-radius, which is free and keeps the PNG cacheable across every site that uses it.

Compared with Crafatar avatars

Crafatar’s /avatars/<uuid> endpoint produces the same kind of image and has served the community well for years. Skin Render’s face endpoint differs in a few ways: it accepts usernames and texture hashes as well as UUIDs, it goes up to 1024 px instead of 512, it never needs a query parameter to include the overlay (the hat is on unless you turn it off), and it shares its URL shape with the 3D head, body and bust renders, so switching from an avatar to a posed body is a one-word change in the path. Switching from Crafatar is mostly a base-URL change: crafatar.com/avatars/<uuid>?size=64 becomes skinrender.dev/render/<uuid>/face?size=64.

Caching and load

Avatars are deterministic: the same URL yields the same bytes until the player changes skin. Responses are sent with Cache-Control: public, max-age=3600, stale-while-revalidate=86400, a strong ETag and Access-Control-Allow-Origin: *, so browsers and CDNs cache them without any work on your part. On our side, finished PNGs are kept in memory for an hour and textures for a day. A list of 200 avatars, once warm, is served from memory in a few milliseconds each. Details are on the caching and limits page.