API Documentation
Welcome to the official documentation for the Mineify.de API. This guide explains how to use our APIs to display Minecraft player heads, skins, and skin coordinates in your projects.
Getting Started
The Mineify.de API is a free service that allows you to display Minecraft player heads, skins, and skin coordinates in your projects. Our API is designed for ease of use - no authentication, API keys, or complex setup required.
Base URL
API Endpoints
- GET
/head/{username|uuid}/{size?}/{overlay?}- Get a player's head - GET
/skin/{username|uuid}/{size?}- Get a player's skin texture - GET
/grid/{username|uuid}/{size?}/{grid?}- Get a player's skin with coordinate grid
Pro Tip
All endpoints support both username and UUID identifiers. UUIDs provide more reliable identification when players change their usernames.
Response Format
All endpoints return PNG images with appropriate cache headers.
Head API
The Head API allows you to display a Minecraft player's head (avatar) in your projects.
Endpoint
Returns the player's head as a PNG image.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
username|uuid |
string | Yes | - | The Minecraft username or UUID of the player |
size |
integer | No | 100 | Size of the image in pixels (16-512) |
overlay |
integer | No | 1 | Show second layer of skin (0=no, 1=yes) |
Examples
Basic Usage (Username)
Using UUID
With Overlay (Default)
Without Overlay
Skin API
The Skin API allows you to display a Minecraft player's complete skin texture.
Endpoint
Returns the player's skin texture as a PNG image.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
username|uuid |
string | Yes | - | The Minecraft username or UUID of the player |
size |
integer | No | 64 | Width of the image in pixels (original aspect ratio is maintained) |
Examples
Original Size
Using UUID
Skin Grid API
The Skin Grid API displays a Minecraft player's skin texture with a coordinate grid overlay. This is useful for developers who need to identify specific regions of a skin texture.
Endpoint
Returns the player's skin texture with a coordinate grid as a PNG image.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
username|uuid |
string | Yes | - | The Minecraft username or UUID of the player |
size |
integer | No | 0 (auto) | Size of the output image in pixels (0 = automatic size) |
grid |
integer | No | 8 | Grid size (pixels between grid lines) |
Additional URL Options
| URL Pattern | Description |
|---|---|
/grid/{username|uuid}/nohl |
Disables region highlighting |
/grid/{username|uuid}/nolabels |
Disables coordinate labels |
/grid/{username|uuid}/simple |
Disables both highlighting and labels |
Examples
Custom Grid Size
Using UUID
Important Skin Coordinates
The grid API highlights these important regions of the skin texture:
| Region | Coordinates (x,y) | Size |
|---|---|---|
| Head (Front) | (8,8) | 8x8 |
| Head (Overlay) | (40,8) | 8x8 |
| Torso (Front) | (20,20) | 8x12 |
| Right Arm (Front) | (44,20) | 4x12 |
| Left Arm (Front) | (36,52) | 4x12 |
| Right Leg (Front) | (4,20) | 4x12 |
| Left Leg (Front) | (20,52) | 4x12 |
UUID Support
All API endpoints now support both usernames and UUIDs as player identifiers.
Minecraft UUIDs (Universally Unique Identifiers) are permanent identifiers assigned to player accounts. Using UUIDs has several advantages over usernames:
Advantages of UUIDs
- Persistent even when players change their usernames
- Guaranteed to be unique across all Minecraft accounts
- More reliable for long-term storage and references
- Eliminates issues with special characters in usernames
UUID Format
UUIDs can be provided in either of these formats:
468e50c4df754beb8c617b5d9d57ff4a (No hyphens)
468e50c4-df75-4beb-8c61-7b5d9d57ff4a (With hyphens)
Using UUIDs in API Requests
Simply replace the username with a UUID in any endpoint:
https://mineify.de/head/468e50c4df754beb8c617b5d9d57ff4a/150/1
https://mineify.de/skin/468e50c4df754beb8c617b5d9d57ff4a/150
https://mineify.de/grid/468e50c4df754beb8c617b5d9d57ff4a/150/8
Finding a Player's UUID
You can find a player's UUID using various online tools, or through the Mojang API.
For example: https://api.mojang.com/users/profiles/minecraft/USERNAME
Rate Limits & Caching
Rate Limits
The Mineify.de API does not impose any specific rate limits. However, our service relies on the Mojang API, which has its own restrictions:
- The Mojang API is limited to approximately 600 requests per 10 minutes per IP address.
- Excessive requests may result in temporary blocks from Mojang's servers.
Caching
To optimize performance and reduce load on Mojang's servers, our API implements the following caching mechanisms:
- Responses are cached for 7 days on our servers
- Responses include appropriate cache headers for browser caching
- ETags are provided for efficient cache validation
For high-traffic applications, we recommend implementing your own caching mechanism to reduce the number of requests to our API. This will improve performance and prevent potential rate limit issues.
Error Handling
When errors occur, the API will return an appropriate HTTP status code along with an error image:
| Status Code | Description |
|---|---|
| 400 Bad Request | Invalid parameters (e.g., missing username/UUID) |
| 404 Not Found | Player not found or no skin available |
| 429 Too Many Requests | Mojang API rate limit exceeded |
| 500 Internal Server Error | Server-side error processing the request |
Instead of standard HTTP error messages, the API returns error images with descriptive text. This ensures that even when errors occur, your application can still display something visually meaningful.