API Overview

Crafatar serves Minecraft avatars, skins, capes, and renders as PNG images using UUID-based routes.

Hosted base URL: https://crafatar.euphoriadevelopment.uk

Supported methods: GET and HEAD.

Endpoints

• Avatar: /avatars/{uuid} (query: size, overlay/helm, default)
• Head render: /renders/head/{uuid} (query: scale, overlay/helm, default)
• Body render: /renders/body/{uuid} (query: scale, overlay/helm, default)
• Skin: /skins/{uuid} (query: default)
• Cape: /capes/{uuid} (query: default)

You can append file extensions like .png to path IDs. Output remains PNG.

GET https://crafatar.euphoriadevelopment.uk/avatars/069a79f444e94726a5befca90e38aaf5?size=128
GET https://crafatar.euphoriadevelopment.uk/renders/head/069a79f444e94726a5befca90e38aaf5?scale=6&overlay
GET https://crafatar.euphoriadevelopment.uk/skins/069a79f444e94726a5befca90e38aaf5.png

Query Parameters

• size: Avatar output pixels. Defaults to 160, allowed range 1-512.
• scale: Render scale multiplier. Defaults to 6, allowed range 1-10.
• overlay: Enables second-layer overlay. Presence means true.
• helm: Legacy alias for overlay.
• default: Fallback when source image is unavailable. Accepts: steve, alex, mhf_steve, mhf_alex, UUID, or external http(s) URL (max length 2048).

UUIDs can be dashed or non-dashed in requests; usernames are always invalid.

Response Behavior

• 200: PNG returned successfully.
• 304: ETag matched, or stale cached image is reused during upstream errors.
• 307: Redirect to fallback from default query.
• 404: Invalid subpath or no result for some resources without fallback.
• 422: Invalid UUID/size/scale/default/render type.
• 500/502: Upstream/server issue without usable fallback image.

Common response headers:

• ETag for conditional requests.
• Cache-Control: max-age=3600 by default.
• Warning on stale/revalidation-failed cached responses.
• X-Storage-Type (cached, downloaded, checked, server error;cached, user error).
• X-Request-ID for support correlation.
• Response-Time in milliseconds.
• Access-Control-Allow-Origin: * for browser usage.

Integration Examples

HTML image

<img
  src="https://crafatar.euphoriadevelopment.uk/avatars/069a79f444e94726a5befca90e38aaf5?size=96&overlay"
  alt="Minecraft avatar"
/>

JavaScript fetch with cache validation

const url = "https://crafatar.euphoriadevelopment.uk/skins/069a79f444e94726a5befca90e38aaf5";
const res = await fetch(url, { headers: { "If-None-Match": previousEtag } });

if (res.status === 304) {
  // Keep existing image
} else if (res.ok) {
  const nextEtag = res.headers.get("etag");
  const blob = await res.blob();
}

Fallback redirect to your own placeholder

https://crafatar.euphoriadevelopment.uk/capes/00000000000000000000000000000000?default=https%3A%2F%2Fcdn.example.com%2Fimg%2Fno-cape.png