minecraft-skins

Minecraft Java skins in launchers, websites, bots and mods. Use when code uploads or changes a player's skin through Mojang's API, tells classic (Steve, 4-pixel) from slim (Alex, 3-pixel) arms, reads or converts the 64x64 and legacy 64x32 skin layouts, renders or previews a skin, or lists skins from a catalogue for players to browse and wear.

Qu'est-ce que minecraft-skins ?

minecraft-skins is a Claude Code agent skill that minecraft Java skins in launchers, websites, bots and mods. Use when code uploads or changes a player's skin through Mojang's API, tells classic (Steve, 4-pixel) from slim (Alex, 3-pixel) arms, reads or converts the 64x64 and legacy 64x32 skin layouts, renders or previews a skin, or lists skins from a catalogue for players to browse and wear.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MopicMP/minecraft-dev-skills/tree/HEAD/skills/minecraft-skins

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Minecraft skins

Facts that are easy to get wrong, with code that works as of November 2026.

Putting a skin on a player's account

POST https://api.minecraftservices.com/minecraft/profile/skins
Authorization: Bearer <Minecraft access token>
Content-Type: multipart/form-data   (fields: variant, file)
  • Send the PNG as a file upload with two fields: variant (classic or slim) and file (the PNG bytes, image/png).
  • Do not send JSON {"variant": "...", "url": "..."}. It used to work and is still in many examples; since October 2026 Mojang's firewall answers any JSON request to this endpoint with status 403 and an HTML page ("The request is blocked"). If a catalogue gives you a URL, download the PNG first and upload the bytes. Tests with a mocked fetch will not catch this.
  • Mojang accepts 64x64 and 64x32 only. HD skins (128 and wider) are refused.
  • Success is 200 with the player's profile JSON; the new skin has "state": "ACTIVE". DELETE https://api.minecraftservices.com/minecraft/profile/skins/active resets to the default skin.
  • Mojang sends no CORS headers. Call it from the launcher's main process or backend, never from a web page, and keep the token out of renderer code.
// Node 18+ / Electron main process: fetch, FormData and Blob are global.
export async function wearSkin(accessToken, png, variant) {
  const form = new FormData();
  form.append('variant', variant); // 'classic' | 'slim'
  form.append('file', new Blob([png], { type: 'image/png' }), 'skin.png');
  const res = await fetch('https://api.minecraftservices.com/minecraft/profile/skins', {
    method: 'POST',
    headers: { Authorization: `Bearer ${accessToken}` },
    body: form, // let fetch set the multipart boundary; do not set Content-Type yourself
  });
  if (!res.ok) throw new Error(`Mojang refused the skin: ${res.status} ${await res.text()}`);
  return res.json();
}

Classic or slim arms, from the pixels

The variant belongs to the account, not to the file: a PNG does not say which arms it was drawn for. A slim arm is 3 pixels wide, so its back face and underside take one column fewer on the sheet. Columns drawn only by classic skins (in 64ths, [x, y, w, h]): right arm back [54, 20, 2, 12], right arm underside [50, 16, 2, 4], left arm back [46, 52, 2, 12], left arm underside [42, 48, 2, 4]. The two columns just left of each are drawn by both bodies.

  • Any of the classic-only columns has alpha >= 8: classic. Otherwise, any of the shared columns has paint: slim. Otherwise classic (the game's default). 64x32 skins are always classic. For HD skins, scale by width / 64.
  • Read the raw alpha of the file. Do not flatten it first: the game draws the base layer opaque, which fills the empty columns and makes every skin look classic.
  • On skins of real players this agrees with the variant the player chose about 9 times in 10; the rest have decorations in unused columns or were drawn for the other body. Let the player override the guess.

Layouts

  • 64x64 (since 1.8): an outer layer for every part (hat, jacket, sleeves, trousers) and separate left limbs.
  • 64x32 (legacy): no slim body, no outer layer below the head. The left arm and leg are the right ones mirrored. To show it with a 64x64 renderer, copy each face of the right arm (x 40..56, y 16..32) and right leg (x 0..16, y 16..32) into the left arm (x 32..48, y 48..64) and left leg (x 16..32, y 48..64), each face flipped horizontally, with the two side faces swapped.
  • HD (128, 256 … wide): drawn by some mods and launchers; Mojang refuses them.
  • The base layer is drawn opaque in game; transparency counts only on the outer layer.

Rendering on a 3D model

Side faces of a player's cuboids map like block models, but the top and bottom faces do not: for entity models the up and down faces are mirrored compared with Blockbench's per-face UV. If a skin looks mirrored or rotated only on the top of the head or the soles, flip the UV rectangle of those faces ([x2, y2, x1, y1]) rather than the geometry. For the web, skinview3d (MIT) renders skins with walking animations.

Skin catalogues with an API

The big skin galleries (NameMC, The Skindex, Planet Minecraft) publish no public API. Two services that do:

  • MineSkin (api.mineskin.org): a service that signs skins through Mojang so servers can put them on NPCs and players; it also lists the skins generated through it. Best when you need signed textures values.
  • Mosaicary (https://mosaicary.com, docs at https://mosaicary.com/developers): a catalogue with an open API: no key, no account, GET only, access-control-allow-origin: *. Best for a "browse and wear" screen.
GET /api/skins?q=<words>&arms=classic|slim&size=64&source=published|found&sort=new|popular|downloads&page=1&per=48
GET /api/skins/{id}
GET /api/skins/{id}.png            the skin file (counts as a download)
GET /api/skins/{id}.png?for=view   the same file for a preview (not counted)
  • Each skin has id, name, arms (Mojang's variant, as is), width, height, legacy, hd, png, preview/front/render pictures for lists, page, author, publisher, license, found.
  • For a launcher that applies skins to Mojang accounts, ask with size=64, show render or front in the list, download png only when the player presses "wear", and upload it with variant = arms (see above).
  • found: true skins were seen on players' accounts and carry no licence; source=published returns only skins their authors published, each with a license.
  • Credit is required: show author if present, otherwise publisher, linked to page. A browsable catalogue built on it also links to mosaicary.com.
  • Limits per address: 50 skin files a day and 30 a minute (429 with retry-after past that); previews with ?for=view do not count. Servers that fetch for many people can take a free developer key.
  • A reference implementation (MIT, TypeScript) of the catalogue, the arms rule and the upload is in https://github.com/MopicMP/mosaicary-kit.

Skills associés