API Documentation

Build amazing Minecraft experiences with MCHeads.org

Request Builder

Preview

Preview

API Endpoints

Minecraft Heads

GET /minecraft/mhf

Returns a list of all available Minecraft Head Format (MHF) heads as a JSON object mapping UUIDs to head names (e.g., "MHF_Creeper", "MHF_Steve", etc.)

Player Routes

GET /player/:input/:size?/:option?

Generates a full body render of a player's skin

GET /head/:input/:size?/:option?

Generates a head render of the player

GET /avatar/:input/:size?/:option?

Generates player head avatars

GET /skin/:input

Returns the raw skin texture of a player

iOS-Specific Routes

GET /iosbody/:input/:size?/:option?

Optimized body renders for iOS devices

GET /ioshead/:input/:size?/:option?

Optimized head renders for iOS devices

Statistics & Downloads

GET /allstats

Returns Java Edition usage stats

GET /allstatsbedrock

Returns Bedrock Edition usage stats

GET /allstatsSorted

Returns sorted usage statistics

GET /download/:input

Downloads player skin textures

Parameters

input

Player username or UUID. Both Java and Bedrock edition players are supported.

size

Image size in pixels. Optional, defaults to 64. Maximum size is 600 pixels.

option

Additional rendering options. Currently supports "nohelm" to exclude the helmet layer.

Examples

HTML

<img src="https://api.mcheads.org/player/Person98/100" alt="Player Avatar" />

CSS Background

.player-avatar {
  background-image: url('https://api.mcheads.org/player/Person98/100');
  width: 100px;
  height: 100px;
}

JavaScript

// Fetch MHF heads
const response = await fetch('https://api.mcheads.org/mhf');
const heads = await response.json();

// Get player skin
const skinUrl = `https://api.mcheads.org/skin/${username}`;

Best Practices

▹

Use appropriate size parameters to minimize bandwidth

▹

Implement client-side caching when possible

▹

Handle error responses appropriately

▹

Use UUIDs instead of usernames for stability

▹

Use the iOS-specific endpoints when developing for iOS platforms

▹

Keep image sizes reasonable (max 600px recommended)