Blockatar

A blazing fast API for Minecraft faces!

Try it

You can use uuid.fail to find the UUID of a username.

Get 10% off a Minecraft server — fast, reliable, and always ready for you and your crew

High-performance hardware designed to hold steady, even when the pressure starts building.

Avatars

avatar
https://blockatar.net/avatars/uuid

Accepted modifiers: size, overlay, default.

Head Renders

head
https://blockatar.net/renders/head/uuid

Accepted modifiers: scale, overlay, default.

Body Renders

body
https://blockatar.net/renders/body/uuid

Accepted modifiers: scale, overlay, default.

Skins

skin
https://blockatar.net/skins/uuid

Accepted modifiers: default.

Capes

cape
https://blockatar.net/capes/uuid

Accepted modifiers: default.

Meta

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 not required, but it is encouraged.
If you want to show some support for this (free!) service, place a notice like this somewhere: Thank you to <a href="https://blockatar.net/">Blockatar</a> for providing avatars.

URL Parameters

You can tweak images using query string parameters.
Example: https://blockatar.net/avatars/853c80ef3c3749fdaa49938b674adae6?size=4&default=MHF_Steve&overlay

  • size: The size for avatars in pixels. 1 - 512
  • scale: The scale factor for renders. 1 - 10
  • overlay: Apply the overlay to the avatar. Presence of this parameter implies true. This option was previously known as helm.
  • default: The fallback to be used when the requested image cannot be served. You can use a custom URL, any uuid, or MHF_Steve/MHF_Alex.
    The option defaults to either MHF_Steve or MHF_Alex, depending on Minecraft's default for the requested UUID.

About UUIDs

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

Malformed UUIDs are rejected.

About Caching

Blockatar checks for skin updates every 20 minutes.
Images are also cached in your browser for 60 minutes unless you clear your browser cache.

After changing your Minecraft skin, you can try clearing your browser cache to see the change faster.

CORS

Blockatar supports Cross-Origin Resource Sharing, so you can make AJAX request from other sites!

HTTP Headers

Blockatar always replies with a 200 OK status code when the requested user's skin/cape was found. This is also used in some rare cases when Mojang servers are having issues and the image couldn't be checked for changes, but Blockatar still had a cached version. 502 Bad Gateway and 500 Server Error are used when no skin/cape was found because of Mojang or Blockatar server issues.

Note that requests are usually answered with an image (with Steve/Alex skin), even if an error occured!

Responses come with some HTTP headers that are useful for debugging.

  • Warning: When using a cached image after an error occured. One of:
    • 110 Blockatar "Response is Stale"
    • 111 Blockatar "Revalidation Failed"
  • X-Storage-Type: Details about how the requested image was stored on the server
    • none: No external requests. Player has no skin (cached)
    • cached: No external requests. (skin cached)
    • checked: Requested skin details, skin cached. (1 external request)
      This happens either when the user removed their skin or when it didn't change.
    • downloaded: Requested skin details, skin downloaded. (2 external requests)
    • server error: This can happen, for example, when Mojang's servers are down.
    • server error;cached: Same as server error, but a cached skin was available.
    • 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.
  • Response-Time: How long it took Blockatar to answer the request, in ms.