WinterAvatar API — Minecraft Skin Rendering (2D & 3D)

A fast, self-healing Minecraft skin rendering library for Node.js. Generate 2D flat sprites and 3D isometric projections of Minecraft skins dynamically by username or UUID.

Try Live Previews View Documentation

Minecraft Username or UUID

Size (px)

Outer Overlay Enabled

3D 3D Full Body Walk

render3dFull()

client.render3dFull('Alex', 384, true)

3D 3D Isometric Bust

render3dBust()

client.render3dBust('Alex', 384, true)

3D 3D Isometric Head

render3dHead()

client.render3dHead('Alex', 384, true)

2D 2D Flat Full Body

render2dFull()

client.render2dFull('Alex', 384, true)

2D 2D Flat Bust

render2dBust()

client.render2dBust('Alex', 384, true)

2D 2D Flat Face

render2dFace()

client.render2dFace('Alex', 384, true)

SKIN Raw Resolved Texture

renderskinRawSkin()

client.renderskinRawSkin('Alex', 384, true)

Library Documentation

A fast, self-healing Minecraft skin renderer for Node.js. Install and render in minutes.

Installation

npm install winter-avatar

Quick Start

import { WinterAvatar } from 'winter-avatar';

const client = new WinterAvatar();
await client.initialize();

// Render a 2D face
const face = await client.render2dFace('Notch', 128, true);

// Render a 3D full body
const full = await client.render3dFull('Alex', 256, true);

// Get raw skin texture
const skin = await client.getRawSkin('Steve');

API Methods

render2dFace (username, size?, overlay?) Flat 2D face render (8x8 grid scaled)

Returns: Promise<Buffer> — PNG image buffer

render2dBust (username, size?, overlay?) Flat 2D front view of head, torso and arms

Returns: Promise<Buffer> — PNG image buffer

render2dFull (username, size?, overlay?) Flat 2D front view of full skin

Returns: Promise<Buffer> — PNG image buffer

render3dHead (username, size?, overlay?) 3D isometric head render

Returns: Promise<Buffer> — PNG image buffer

render3dBust (username, size?, overlay?) 3D isometric upper body render

Returns: Promise<Buffer> — PNG image buffer

render3dFull (username, size?, overlay?) 3D isometric full body in walking pose

Returns: Promise<Buffer> — PNG image buffer

getRawSkin (username) Raw resolved skin texture file (64x64 or 64x32)

Returns: Promise<Buffer> — PNG image buffer

Parameters

Parameter	Type	Default	Description
`username`	String	—	Minecraft username or UUID to resolve the skin for
`size`	Integer	`128`	The size of the output image in pixels. Clamped between `8` and `2048`. For full bodies/busts, size dictates output height.
`overlay`	Boolean	`true`	Whether to render the secondary outer layer (hats, jacket sleeves, pant layers). Pass `false` to disable.

Examples

// Node.js (ESM): render a 2D face and save to disk
import { WinterAvatar } from 'winter-avatar';
import { writeFile } from 'node:fs/promises';

const client = new WinterAvatar();
await client.initialize();

const buffer = await client.render2dFace('Notch', 128, true);
await writeFile('notch_face.png', buffer);

// Node.js (ESM): render a 3D bust and save to disk
import { WinterAvatar } from 'winter-avatar';
import { writeFile } from 'node:fs/promises';

const client = new WinterAvatar();
await client.initialize();

const buffer = await client.render3dBust('Steve', 256, true);
await writeFile('steve_bust.png', buffer);

// Node.js (ESM): get raw skin texture
import { WinterAvatar } from 'winter-avatar';
import { writeFile } from 'node:fs/promises';

const client = new WinterAvatar();
await client.initialize();

const buffer = await client.getRawSkin('Alex');
await writeFile('alex_skin.png', buffer);

// Express.js: serve avatars via HTTP
import { WinterAvatar } from 'winter-avatar';
import express from 'express';

const app = express();
const avatar = new WinterAvatar();
await avatar.initialize();

app.get('/avatar/:name', async (req, res) => {
  const buffer = await avatar.render2dFace(
    req.params.name,
    parseInt(req.query.size) || 128,
    req.query.overlay !== 'false'
  );
  res.type('png').send(buffer);
});

app.listen(3000);