API Documentation

Complete reference for the MC Heads API.

◆ Parameters

{player}— Username, UUID, or XUID. For Bedrock players, prefix with a dot (e.g., .PlayerName)

{size}— Image size in pixels (16-512, default 128)

{direction}— left or right (iOS routes only)

◆ Renders

GET/head/{player}

Player head (default 128px)

https://api.mcheads.org/head/Notch

GET/head/{player}/{size}

Player head with custom size

https://api.mcheads.org/head/Notch/64

GET/avatar/{player}/{direction}

Player avatar (left or right)

https://api.mcheads.org/avatar/jeb_/left

GET/avatar/{player}/{direction}/{size}

Player avatar with custom size

https://api.mcheads.org/avatar/jeb_/right/128

GET/player/{player}

Full player body

https://api.mcheads.org/player/Dinnerbone

GET/player/{player}/{size}

Full player body with custom size

https://api.mcheads.org/player/Dinnerbone/256

GET/skin/{player}

Raw skin texture

https://api.mcheads.org/skin/Notch

◆ iOS

GET/ioshead/{player}/{direction}/{size}

iOS-optimized head (left/right)

https://api.mcheads.org/ioshead/Notch/left/512

GET/iosbody/{player}/{direction}/{size}

iOS-optimized body (left/right)

https://api.mcheads.org/iosbody/Notch/right/512

◆ Data

GET/health

API health status

https://api.mcheads.org/health

GET/allstats

Java edition statistics

https://api.mcheads.org/allstats

GET/allstatsbedrock

Bedrock edition statistics

https://api.mcheads.org/allstatsbedrock

GET/minecraft/mhf

MHF head list

https://api.mcheads.org/minecraft/mhf

◆ Download

GET/download/{player}

Download skin file

https://api.mcheads.org/download/Notch

◆ Examples

HTML

<img src="https://api.mcheads.org/head/Notch/64" alt="Notch" />

JavaScript

fetch('https://api.mcheads.org/avatar/Notch/128')
  .then(res => res.blob())
  .then(blob => {
    // Use the image blob
  });

Bedrock Player

https://api.mcheads.org/head/.BedrockPlayer/128

◆ Response Format

Image endpoints— Return PNG with appropriate Content-Type header

Data endpoints— Return JSON

Caching— Images are cached for 1 hour