<%# FIXME: Use CDN %> Fork me on GitHub

Crafatar

A blazing fast API for Minecraft faces!

<%# These are shuffled by JS %>

Try it

Avatars

avatar
<%= domain %>/avatars/uuid

Accepted parameters: size, helm, default.

Head Renders

head
<%= domain %>/renders/head/uuid

Accepted parameters: scale, helm, default.
Please note renders are still beta and have some issues. New renders are in progress!

Body Renders

body
<%= domain %>/renders/body/uuid

Accepted parameters: scale, helm, default.
Please note renders are still beta and have some issues. New renders are in progress!

Skins

skin
<%= domain %>/skins/uuid

Accepted parameters: default.

Capes

cape
<%= domain %>/capes/uuid

Accepted parameters: default.

Meta

In the examples above, you can generally use usernames instead of uuid. However, apart from the special cases MHF_Steve and MHF_Alex this is discouraged as explained below.
You can append .png or any other file extension to the URL path if you like to, but all images are PNG.

Attribution

Attribution is encouraged but not required.
If you want to show some support for this (free!) service, place a notice like this somewhere:

Thank you to <a href="https://crafatar.com">Crafatar</a> for providing avatars.

URL Parameters

You can tweak images using query string parameters.
Example: <%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6?size=4&default=MHF_Steve&helm

  • size: The size of the image in pixels. <%= config.avatars.min_size %> - <%= config.avatars.max_size %>
  • scale: The scale factor renders. <%= config.renders.min_scale %> - <%= config.renders.max_scale %>
  • helm: Apply the overlay to the avatar. Presence of this parameter implies true.
  • default: The fallback to be used when the requested image cannot be served. You can use a custom URL or any uuid.
    The option defaults to either MHF_Steve or MHF_Alex, depending on the requested UUID. All usernames default to MHF_Steve.

About UUIDs

UUIDs may be any valid Mojang UUID in the blank or dashed format.

Malformed UUIDs are rejected.

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 Caching

Crafatar caches skins for <%= config.caching.local / 60 %> minutes before checking for skin updates.
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.

CORS

Crafatar supports CORS, so you can make AJAX request from other sites!

HTTP Headers

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

  • 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.

Contact