Crafatar

Usernames are deprecated!

You should only use usernames for testing.
Updates are slower, some features are not available, and it may break anytime!
We strongly advise you to use UUIDs instead of usernames. more info

Documentation

Avatars

<%= domain %>/avatars/uuid

Avatar Parameters

parameter	type	default	description
size	integer	<%= config.avatars.default_size %>	The size of the image in pixels, <%= config.avatars.min_size %> - <%= config.avatars.max_size%>.
default	string	The standard value is calculated based on the UUID (even = MHF_Alex, odd = MHF_Steve). Usernames always default to MHF_Steve.	The image to be served when the player has no skin. Valid options are any name or uuid, including MHF_Steve and MHF_Alex, or a custom URL.
helm	null		Apply the "second" layer (hat) to the avatar.

Avatar Examples

<%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6

Jeb's avatar

<%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6?helm

Jeb's avatar with helm

<%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6?size=128

Jeb's avatar, 128 × 128

<%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6

Jeb's avatar by UUID

<%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6?default=MHF_Alex

Jeb's avatar, or fall back to MHF_Alex (this example assumes jeb_ does not exist)

<%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6?default=https%3A%2F%2Fi.imgur.com%2FocJVWAc.png

Jeb's avatar, or fall back to a custom image (this example assumes jeb_ does not exist)

Hover over the example URLs above for a preview!

Crafatar also provides support for 3D renders of Minecraft skins.
Please note that this feature is currently beta!
The head render type returns a render of the skin's head.<%= domain %>/renders/head/uuidThe body render returns a render of the entire skin.<%= domain %>/renders/body/uuid

Render Parameters

parameter	type	default	description
scale	integer	<%= config.renders.default_scale %>. The actual size differs between the type of render.	The scale factor of the image <%= config.renders.min_scale %> - <%= config.renders.max_scale %>.
helm	null		Apply the "second" layer (hat) to the avatar.
default	string	The standard value is calculated based on the UUID (even = MHF_Alex, odd = MHF_Steve). Usernames always default to MHF_Steve.	The image to be served when the uuid has no skin. Valid options are any uuid, including MHF_Steve and MHF_Alex, or a custom URL.

Render Examples

<%= domain %>/renders/body/853c80ef3c3749fdaa49938b674adae6?helm&scale=4

Jeb's body, with helmet, scale 4

<%= domain %>/renders/head/853c80ef3c3749fdaa49938b674adae6?scale=8

Jeb's head, by UUID, scale 8

Hover over the example URLs above for a preview!

Skins

You can also get the full skin file of a player.
The user's skin is returned, or the default image is served.
You can use the default parameter here as well.<%= domain %>/skins/uuid

Skin Parameters

parameter	type	default	description
default	string	The standard value is calculated based on the UUID (even = MHF_Alex, odd = MHF_Steve). Usernames always default to MHF_Steve.	The image to be served when the uuid has no skin. Valid options are any uuid, including MHF_Steve and MHF_Alex, or a custom URL.

Skin Examples

<%= domain %>/skins/853c80ef3c3749fdaa49938b674adae6

Jeb's skin

<%= domain %>/skins/853c80ef3c3749fdaa49938b674adae6?default=MHF_Alex

Jeb's skin, or fall back to MHF_Alex (this example assumes jeb_ does not exist)

Hover over the example URLs above for a preview!

Capes

A cape endpoint is also available to get the active cape of a user.
The user's cape is returned, otherwise a 404 is returned.

<%= domain %>/capes/uuid

Cape Examples

<%= domain %>/capes/61699b2ed3274a019f1e0ea8c3f06bc6

Dinnerbone's Cape Mojang capes are not transparent...

<%= domain %>/capes/af74a02d19cb445bb07f6866a861f783

md_5's Cape

Hover over the example URLs above for a preview!

Meta

CORS

Crafatar supports CORS so you can make AJAX request from within the browser!

HTTP Headers

Responses come with these HTTP headers, useful for debugging.
Please note that these headers are cached by CloudFlare (CF-Cache-Status: HIT).

Response-Time

The time, in milliseconds, it took Crafatar to process the request.

X-Storage-Type

Details about how the requested image was stored on the server

none: No external requests. Cached: User has no skin.
cached: No external requests. Skin cached and stored locally.
checked: 1 external request. Skin cached, checked for updates, no skin downloaded.
This happens either when the user removed their skin or when it didn't change.
downloaded: 2 external requests. First request or skin changed, skin downloaded.
server error: This can happen, for example, when Mojang's servers are down.
If possible, a cached image is served instead.
user error: You have done something wrong, such as requesting a malformed uuid.
Check the response body for details.

X-Request-ID

The internal ID assigned to this request.
If you think something is wrong with your request, please contact us and provide this ID.

About Usernames

We strongly advise you to use UUIDs instead of usernames! UUIDs never change while usernames do.
Looking up players by username has officially been deprecated by Mojang ever since UUIDs were introduced.
Crafatar uses a legacy API to retrieve skins for usernames that updates very slowly.
Skins come without any details, including whether a player uses the Alex or Steve skin model.
Additionally, Mojang has stated that this legacy interface may be disabled anytime, causing all requests to fail.
Malformed usernames are rejected.

About UUIDs

UUIDs may use the blank or dashed format.
Malformed UUIDs are rejected.

About Caching

Crafatar caches skins for <%= config.caching.local / 60 %> minutes before checking for skin changes.
Images are cached in your browser for <%= config.caching.browser / 60 %> minutes until a new request to Crafatar is made.
When you changed your skin you can try clearing your browser cache to see the change faster.