API reference

Documentation

The mcskin API resolves Minecraft usernames or UUIDs through the official Mojang servers, fetches the skin texture and renders ready-to-use PNG images: raw texture, face, head with hat layer, full body and a stylized avatar.

Every endpoint is a GET and needs no API key. Image endpoints return image/png; service endpoints return JSON.

Base URL

All paths are relative to the public base URL:

https://api.mcskin.me

Authentication

None. The API is public and free — no key, no headers, no registration. Use the URLs directly in an <img> tag.

Players & UUIDs

The path parameter {player} accepts both:

• a username, e.g. Notch
• a UUID, with or without dashes, e.g. 069a79f4-44e9-4726-a5be-fca90e38aaf5

Usernames are resolved to a UUID via Mojang and cached. Case is ignored.

Image size

Control the output with ?size=N.

Invalid or out-of-range values fall back to the default; values above 512 are clamped. Scaling is nearest-neighbor, so pixels stay sharp — set image-rendering: pixelated in CSS.

Caching

The API keeps a TTL cache for profiles (name→UUID) and skin textures (default 30 minutes). Image responses also send Cache-Control: public, max-age=300. The /skin endpoint returns an X-Skin-Model header (classic or slim).

Raw skin texture

Returns the unmodified 64×64 skin texture as stored by Mojang. size is ignored here. Includes the X-Skin-Model header.

curl "https://api.mcskin.me/skin/Notch" -o skin.png

Face

The 8×8 face region (without hat layer), scaled to size×size.

curl "https://api.mcskin.me/face/Notch?size=256" -o face.png

Head

The face with the hat/overlay layer composited on top. Ideal as a player icon.

curl "https://api.mcskin.me/head/jeb_?size=128" -o head.png

Avatar

Alias for /head — identical output, when “avatar” reads better in your app.

curl "https://api.mcskin.me/avatar/Notch?size=128" -o avatar.png

Body

A flat, front-facing full-body render (head, torso, arms, legs). Width is roughly size px; the image is twice as tall as wide.

curl "https://api.mcskin.me/body/Notch?size=256" -o body.png

Bust avatar (pfp)

A stylized 20×20 bust (head + shoulders) on a transparent background with subtle shading. Supports modern (64×64) and legacy (64×32) skins. Great as a profile picture.

curl "https://api.mcskin.me/pfp/Notch?size=200" -o pfp.png

Health check

Lightweight health check for monitoring. Always returns 200.

{ "status": "ok" }

API overview

A machine-readable overview of all endpoints as JSON.

{
  "name": "mcskins",
  "endpoints": [
    "GET /skin/{player}",
    "GET /face/{player}?size=N",
    "GET /head/{player}?size=N",
    "GET /avatar/{player}?size=N",
    "GET /body/{player}?size=N",
    "GET /pfp/{player}?size=N",
    "GET /health"
  ],
  "notes": "player = username or UUID; size 1-512 (default 128)"
}

Errors & status codes

Image endpoints return JSON on error.

Fallback skin

If a player exists but has no skin set, that is not an error: the API returns a deterministic default skin (Steve or Alex) derived from the UUID. You always get a valid image as long as the player exists.

Self-hosting

The API is open source (Go, standard library only, no external dependencies) and runs in seconds.

# run directly
go run ./cmd/mcskins

# or build
go build -o mcskins ./cmd/mcskins && ./mcskins

docker build -t mcskins .
docker run -p 3000:3000 mcskins

Configuration

Source: tinybrickboy/mcskin-api.