Introduction

Everything you need to integrate Minecraft avatars into your project.

TAB avatars API allows you to fetch player avatars for both Java Edition and Bedrock Edition players. Simply use an image tag with our endpoint URL, and we'll return the player's avatar as a PNG image.

No API Key Required!

Just start using the API immediately. No registration, no authentication.

Quick Start

Add this to your HTML and replace the username:

HTML
<img src="https://tabavatars.net/avatar/?username=Technoblade" alt="Technoblade">

Result

Technoblade's avatar

API Endpoint

The base URL for all avatar requests.

All avatar requests go through a single endpoint:

GET /avatar/

Identifier Options

Use one of these to identify the player:

Examples
https://tabavatars.net/avatar/?username=Technoblade
https://tabavatars.net/avatar/?uuid=b876ec32e396476ba1158438d83c67d4
https://tabavatars.net/avatar/?xuid=2535441133062698
https://tabavatars.net/avatar/?texture=38919ff0454c800f2209cc6f962b17a4db0165c1bb61ae326f3b9aaf0cea3ddb

The API returns a PNG image that can be used directly in <img> tags, CSS backgrounds, or downloaded programmatically.

Response

Header	Value	Description
Content-Type	image/png	Always returns PNG format
Access-Control-Allow-Origin	*	CORS enabled for all origins

Parameters

Configure your avatar request using URL parameters.

Identifier Parameters

Use ONE of these to identify the player (in priority order):

Parameter	Description	Example
texture	Direct Minecraft texture IDoptional	38919ff0454c800f2209cc6f962b17a4db0165c1bb61ae326f3b9aaf0cea3ddb
xuid	Xbox User ID for Bedrock playersoptional	2535441133062698
uuid	Java UUID or Floodgate UUIDoptional	b876ec32e396476ba1158438d83c67d4
username	Minecraft username or Xbox Gamertagoptional	Technoblade, T4B1762

Display Options

Parameter	Description	Values	Default
size	Output image size in pixelsoptional	8 - 512	100
type	Type of avatar to renderoptional	head, helm, body, bust, head-iso, head-iso-left, body-iso, body-iso-left, front, back, left, right, skin	head
platform	Specify platform when using usernameoptional	java, bedrock	java
angle	Side angle for bust renderoptional	left, right	right
shadow	Enable depth shading for bust renderoptional	true, false	true

Automatic Platform Detection

You don't always need to specify platform=bedrock for Bedrock players! When you request a username without specifying the platform, the API will:

First check if the username exists as a Java Edition player
If no Java skin is found, automatically check Bedrock Edition
If both fail, return the default Steve skin

This means ?username=T4B1762 works just as well as ?username=T4B1762&platform=bedrock for Bedrock players!

Priority Order

If multiple identifiers are provided, the API uses them in this order: texture → xuid → uuid → username

Complete Examples

Here are working examples for every parameter combination:

Java Edition Examples

Username Only

Default settings

https://tabavatars.net/avatar/?username=Technoblade

Username + Size

128px size

https://tabavatars.net/avatar/?username=Technoblade&size=128

Username + Type

Full body

https://tabavatars.net/avatar/?username=Technoblade&type=body

Username + All Options

All params specified

https://tabavatars.net/avatar/?username=Technoblade&size=100&type=helm&platform=java

UUID (no dashes)

32 hex chars

https://tabavatars.net/avatar/?uuid=b876ec32e396476ba1158438d83c67d4

UUID (with dashes)

Standard format

https://tabavatars.net/avatar/?uuid=b876ec32-e396-476b-a115-8438d83c67d4

Texture ID

Direct texture

https://tabavatars.net/avatar/?texture=38919ff0454c800f2209cc6f962b17a4db0165c1bb61ae326f3b9aaf0cea3ddb

Texture + Size + Type

Full control

https://tabavatars.net/avatar/?texture=38919ff0454c800f2209cc6f962b17a4db0165c1bb61ae326f3b9aaf0cea3ddb&size=150&type=body

Bedrock Edition Examples

Tip: Thanks to automatic platform detection, you can also use just ?username=T4B1762 without specifying platform=bedrock - the API will automatically find Bedrock players!

Gamertag Only (Auto-detect)

Auto-detects Bedrock

https://tabavatars.net/avatar/?username=T4B1762

Gamertag + Platform

Manually specified

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock

Gamertag + Size

128px size

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&size=128

Gamertag + Body Type

Full body

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&type=body

Gamertag + All Options

Complete params

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&size=100&type=helm

XUID Only

No platform needed

https://tabavatars.net/avatar/?xuid=2535441133062698

XUID + Size + Type

Full control

https://tabavatars.net/avatar/?xuid=2535441133062698&size=150&type=body

Floodgate UUID

Auto-detects Bedrock

https://tabavatars.net/avatar/?uuid=00000000-0000-0000-0009-01f86415ca2a

Floodgate + Options

Size and type work

https://tabavatars.net/avatar/?uuid=00000000-0000-0000-0009-01f86415ca2a&size=150&type=body

URL Parameter Syntax

Remember: The first parameter uses ? but additional parameters must use &. Example: ?username=Name&size=100&type=helm

Render Types

Choose from multiple avatar formats including 2D and 3D isometric renders.

Basic 2D Types

Head

Clean face without overlay

https://tabavatars.net/avatar/?username=Technoblade&type=head

Helm

Face with helmet/hat layer

https://tabavatars.net/avatar/?username=Technoblade&type=helm

Body

Full front body render

https://tabavatars.net/avatar/?username=Technoblade&type=body

Bust Portrait Type

Stylized 2.5D portrait render - perfect for profile pictures! Shows head with side depth and upper body.

Bust (Right)

Portrait with right side visible

https://tabavatars.net/avatar/?username=Technoblade&type=bust

Bust (Left)

Portrait with left side visible

https://tabavatars.net/avatar/?username=Technoblade&type=bust&angle=left

Bust (No Shadow)

Portrait without depth shading

https://tabavatars.net/avatar/?username=Technoblade&type=bust&shadow=false

Bust (Left, No Shadow)

Left-facing without shading

https://tabavatars.net/avatar/?username=Technoblade&type=bust&angle=left&shadow=false

Bust (Bedrock)

Works with Bedrock players too

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&type=bust

3D Isometric Types

Beautiful 3D isometric renders showing multiple faces of the skin:

Java Edition

Head Iso

3D head (right-facing)

https://tabavatars.net/avatar/?username=Technoblade&type=head-iso

Head Iso Left

3D head (left-facing)

https://tabavatars.net/avatar/?username=Technoblade&type=head-iso-left

Body Iso

3D full body (right-facing)

https://tabavatars.net/avatar/?username=Technoblade&type=body-iso

Body Iso Left

3D full body (left-facing)

https://tabavatars.net/avatar/?username=Technoblade&type=body-iso-left

Bedrock Edition

Head Iso

3D head (right-facing)

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&type=head-iso

Head Iso Left

3D head (left-facing)

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&type=head-iso-left

Body Iso

3D full body (right-facing)

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&type=body-iso

Body Iso Left

3D full body (left-facing)

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock&type=body-iso-left

2D Body Views

Flat 2D renders from different angles:

Front

Full body front view

https://tabavatars.net/avatar/?username=Technoblade&type=front

Back

Full body back view

https://tabavatars.net/avatar/?username=Technoblade&type=back

Right

Body right side view

https://tabavatars.net/avatar/?username=Technoblade&type=right

Left

Body left side view

https://tabavatars.net/avatar/?username=Technoblade&type=left

Raw Skin File

Get the complete skin texture file (64x64 PNG):

Skin

Full skin texture file

https://tabavatars.net/avatar/?username=Technoblade&type=skin

Note

The skin type ignores the size parameter and always returns the original skin dimensions (usually 64x64 pixels).

Tip

The helm type is most popular for simple avatars. For more dynamic displays, try the 3D isometric types like head-iso or body-iso!

Java EditionJava

Fetch avatars for Java Edition players using their Minecraft username or UUID.

How It Works

You provide a Minecraft username (e.g., "Technoblade") or UUID
We look up the player's UUID from Mojang's API (if username provided)
We fetch the player's skin texture from Mojang's session server
We extract and render the requested avatar type
PNG image is returned to you

Examples

By Username

Technoblade

https://tabavatars.net/avatar/?username=Technoblade

By UUID

Technoblade

https://tabavatars.net/avatar/?uuid=b876ec32e396476ba1158438d83c67d4

With Helmet Layer

Helm type

https://tabavatars.net/avatar/?username=Technoblade&type=helm

Full Body

Body render

https://tabavatars.net/avatar/?username=Technoblade&type=body

Pro Tip

Using UUID instead of username is more reliable as UUIDs never change, even when players change their name.

Note

Java Edition usernames are case-insensitive. "Technoblade", "TECHNOBLADE", and "technoblade" will all return the same avatar.

Bedrock EditionBedrock

Fetch avatars for Bedrock Edition players using their Xbox Gamertag or XUID.

For Bedrock Edition players, use their Xbox Gamertag with platform=bedrock, or directly use their XUID. The API uses GeyserMC's API to fetch their skin.

How It Works

You provide an Xbox Gamertag (e.g., "T4B1762") or XUID
We look up the player's XUID from GeyserMC's API (if gamertag provided)
We fetch the player's skin texture URL
We download and process the skin texture
We extract and render the requested avatar type
PNG image is returned to you

Examples

By Gamertag

Bedrock player

https://tabavatars.net/avatar/?username=T4B1762&platform=bedrock

By XUID (no platform needed)

Direct XUID

https://tabavatars.net/avatar/?xuid=2535441133062698

XUID is simpler!

When using xuid parameter, you don't need to specify platform=bedrock - it's automatically detected.

About Xbox Gamertags

Xbox Gamertags may contain spaces and special characters. Make sure to URL-encode the gamertag if it contains special characters.

Custom Skins

Bedrock players using marketplace skins may show a default Steve/Alex skin if their skin isn't accessible through the GeyserMC API.

UUID & XUID

Fetch avatars using unique identifiers instead of usernames.

Using UUIDs and XUIDs is more reliable than usernames because they never change, even if the player changes their name.

Java UUID

Use the uuid parameter with a Java Edition player's UUID (with or without dashes):

UUID without dashes

Technoblade's UUID

https://tabavatars.net/avatar/?uuid=b876ec32e396476ba1158438d83c67d4

UUID with dashes

Also works!

https://tabavatars.net/avatar/?uuid=b876ec32-e396-476b-a115-8438d83c67d4

Bedrock XUID

Use the xuid parameter directly for Bedrock players (no platform needed):

Direct XUID

Bedrock via XUID

https://tabavatars.net/avatar/?xuid=2535441133062698

Floodgate UUID

Bedrock players on Java servers using GeyserMC/Floodgate have special UUIDs that start with 00000000-0000-0000-. The API automatically detects and handles these:

Floodgate UUID

Auto-detected Bedrock

https://tabavatars.net/avatar/?uuid=00000000-0000-0000-0009-01f86415ca2a

Smart Detection

The API automatically detects Floodgate UUIDs and fetches the Bedrock skin - no need to specify platform=bedrock!

Texture ID

Use Minecraft texture IDs directly for maximum flexibility.

If you already have the Minecraft texture ID (the hash from textures.minecraft.net), you can use it directly without any API lookups:

Direct Texture ID

From texture ID

https://tabavatars.net/avatar/?texture=38919ff0454c800f2209cc6f962b17a4db0165c1bb61ae326f3b9aaf0cea3ddb

Where to find Texture IDs

Server plugins like TAB, LuckPerms that cache skin data
Mojang session server responses
Skin databases and skin editors
URLs like textures.minecraft.net/texture/{texture_id}

Fastest Method

Using texture IDs is the fastest way to get avatars since it skips the username/UUID lookup entirely.

HTML Examples

Copy-paste code snippets for your project.

Simple Image Tag

HTML
<!-- Java Edition player -->
<img src="https://tabavatars.net/avatar/?username=Technoblade&size=100&type=helm" alt="Technoblade">

<!-- Bedrock Edition player -->
<img src="https://tabavatars.net/avatar/?username=T4B1762&size=100&type=helm&platform=bedrock" alt="T4B1762">

Player List

HTML
<div class="player-list">
    <div class="player">
        <img src="https://tabavatars.net/avatar/?username=Technoblade&size=32&type=helm" alt="Technoblade">
        <span>Technoblade</span>
    </div>
    <div class="player">
        <img src="https://tabavatars.net/avatar/?username=Dream&size=32&type=helm" alt="Dream">
        <span>Dream</span>
    </div>
</div>

CSS Background

CSS
.player-avatar {
    width: 64px;
    height: 64px;
    background-image: url('https://tabavatars.net/avatar/?username=Technoblade&size=64&type=helm');
    background-size: cover;
    image-rendering: pixelated;
}

JavaScript Examples

Dynamic avatar loading with JavaScript.

Helper Function

JavaScript
function getAvatarUrl(username, options = {}) {
    const { size = 100, type = 'helm', platform = 'java' } = options;
    const base = 'https://tabavatars.net/avatar/';
    let url = `${base}?username=${encodeURIComponent(username)}&size=${size}&type=${type}`;
    if (platform === 'bedrock') url += '&platform=bedrock';
    return url;
}

// Usage:
const avatar = getAvatarUrl('Technoblade', { size: 64 });
const bedrockAvatar = getAvatarUrl('T4B1762', { platform: 'bedrock' });

React Component

React / JSX
function MinecraftAvatar({ username, size = 64, type = 'helm', platform = 'java' }) {
    const base = 'https://tabavatars.net/avatar/';
    let src = `${base}?username=${encodeURIComponent(username)}&size=${size}&type=${type}`;
    if (platform === 'bedrock') src += '&platform=bedrock';
    
    return <img src={src} alt={`${username}'s avatar`} style={{ imageRendering: 'pixelated' }} />;
}

// Usage:
<MinecraftAvatar username="Technoblade" size={100} />
<MinecraftAvatar username="T4B1762" platform="bedrock" />

Caching

How the API caches avatars for optimal performance.

TAB avatars uses multiple layers of caching to ensure fast response times and reduce load on upstream APIs.

Cache Layers

Layer	Duration	Description
Server Cache	24 hours	Rendered avatars are cached on our server for 24 hours to reduce processing
Browser Cache	1 hour	Images are sent with cache headers allowing browsers to cache for 1 hour
CDN Cache	Varies	CloudFlare may cache images for as long as your browser would

Skin Updates

If a player changes their skin, it may take up to 24 hours for the new skin to appear due to caching. This is normal behavior.

Performance Benefit

Caching significantly improves response times. Cached avatars typically load in under 50ms!

Self-Hosting for Longer Cache

If you need longer cache times or want full control over caching, you can download avatars from our API and store them on your own server:

PHP Example
// Download and save avatar to your server
$username = 'Technoblade';
$avatarUrl = "https://tabavatars.net/avatar/?username={$username}&size=100&type=helm";
$avatarData = file_get_contents($avatarUrl);
file_put_contents("avatars/{$username}.png", $avatarData);

// Then serve from your own server with custom cache headers

When to Self-Host

Consider downloading and caching avatars locally if you need cache times longer than 24 hours, want to reduce external dependencies, or have strict performance requirements.

Rate Limiting

Understanding API rate limits and how to handle them.

To ensure fair usage and protect the service, the API enforces rate limiting on requests.

Current Limits

Limit	Value	Description
`Requests`	`300`	Maximum requests per time window
`Time Window`	`1 minute`	Rate limit resets every minute

Rate Limit Response

When you exceed the rate limit, the API returns a 429 Too Many Requests error:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait 1 minute before trying again.",
  "limit": "300 requests per minute"
}

Best Practices

Cache avatar images on your own server when possible. Don't request the same avatar repeatedly - use browser caching or download once and store locally.

Headers

When rate limited, the response includes:

Retry-After: 60 - Seconds to wait before retrying

Need Higher Limits?

If you need higher rate limits for your project, contact us at [email protected]

Error Handling

How the API handles errors and edge cases.

The API handles errors gracefully and returns a default Steve skin when:

The username doesn't exist
The player hasn't set a custom skin
The Mojang/GeyserMC API is temporarily unavailable
The skin texture couldn't be downloaded

Always Returns an Image

The API will always return a valid PNG image, even if there's an error. This means your website won't have broken images.

Contact

Get in touch with us for support or questions.

Have questions, feedback, or need help integrating TAB avatars into your project? We're here to help!

Email Support

Send us an email at: [email protected]

Response Time

We typically respond to emails within 24-48 hours. For urgent issues, please include "URGENT" in your subject line.