API Documentation
Build amazing Minecraft experiences with MCHeads.org
Request Builder
Preview
API Endpoints
Minecraft Heads
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
Generates a full body render of a player's skin
Generates a head render of the player
Generates player head avatars
Returns the raw skin texture of a player as PNG
iOS-Specific Routes
Optimized body renders for iOS devices. Direction must be "left" or "right".
Optimized head renders for iOS devices. Direction must be "left" or "right".
Statistics & Downloads
Returns Java Edition usage stats
Returns Bedrock Edition usage stats
Returns sorted usage statistics
Downloads player skin texture as a file attachment
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.
direction
For iOS endpoints only. Use "left" or "right" to control the rendering direction.
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)