HomeDocumentationPlaygroundStatisticsHealthAbout
API Status: Checking...

API Documentation

Complete reference for all MC Heads API endpoints

Complete API Documentation

GET/head/{player}

Get player head (default size: 128px)

Example:

https://api.mcheads.org/head/JaceDev
GET/head/{player}/{size}

Get player head with custom size

Example:

https://api.mcheads.org/head/JaceDev/64
GET/head/{player}/{size}.png

Get player head with explicit PNG format

Example:

https://api.mcheads.org/head/JaceDev/64.png
GET/avatar/{player}

Get player avatar (head with shoulders)

Example:

https://api.mcheads.org/avatar/jeb_
GET/avatar/{player}/{size}

Get player avatar with custom size

Example:

https://api.mcheads.org/avatar/jeb_/128
GET/avatar/{player}/{size}.png

Get player avatar with explicit PNG format

Example:

https://api.mcheads.org/avatar/jeb_/128.png
GET/player/{player}

Get full player render

Example:

https://api.mcheads.org/player/Dinnerbone
GET/player/{player}/{size}

Get full player render with custom size

Example:

https://api.mcheads.org/player/Dinnerbone/256
GET/player/{player}/{size}.png

Get full player render with explicit PNG format

Example:

https://api.mcheads.org/player/Dinnerbone/256.png
GET/skin/{player}

Get player skin texture

Example:

https://api.mcheads.org/skin/JaceDev
GET/skin/{player}.png

Get player skin texture with explicit PNG format

Example:

https://api.mcheads.org/skin/JaceDev.png

Parameters

{player}

Minecraft username, UUID, XUID, or gamertag. For Bedrock players, prefix with a dot (e.g., .BedrockPlayer)

{size}

Image size in pixels (optional, default: 128). Supports sizes from 16px to 512px

{direction}

For iOS routes only: "left" or "right" orientation

Response Format

Image Endpoints

Returns PNG image data with proper Content-Type headers

Statistics Endpoints

Returns JSON data with player statistics and usage information

Health Endpoint

Returns JSON with API status and uptime information

Usage Examples

HTML Image Tag

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

JavaScript Fetch

fetch('https://api.mcheads.org/avatar/JaceDev/128') .then(response => response.blob())

CSS Background

.avatar { background-image: url('https://api.mcheads.org/avatar/JaceDev'); }

Bedrock Player

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