Skip to content

API documentation

All endpoints accept a Minecraft username or a UUID (with or without dashes). Short paths like /bust/{player} are the canonical links; the same renders also live under /api/skins/{player}/bust. Image endpoints return PNG and are cached at the edge for an hour. Lookups hit Mojang and are cached for ten minutes. Head, bust and body are rendered in 3D with perspective and lighting; add style=flat (or style=iso for the head) to get the flat 2D variants instead. Capes come from OptiFine first and Mojang second, exactly as they show up in game. Every image endpoint also takes download=1 to return the PNG as a file download.

  1. GET

    /lookup/{player}

    Resolve a username or UUID to a profile with skin model, cape sources and render links.

    player
    Username (1–16 chars) or UUID.
    https://mccatalog.com/lookup/Notch
  2. GET

    /face/{player}

    2D face with hat layer.

    size
    Output width in px, 8–1024. Default 128.
    overlay
    Set to false to hide the hat layer.
    https://mccatalog.com/texture/6c38aba62a532aa0333dc8336274c13cd84d718aea5141cf704aef3ac5d6a48f/face?size=64
    Example output for /face/{player}
  3. GET

    /head/{player}

    3D head in perspective. /skull/{player} is an alias.

    size
    Output width in px, 16–1024. Default 256.
    overlay
    Set to false to hide the hat layer.
    style
    iso for a flat isometric head.
    https://mccatalog.com/texture/6c38aba62a532aa0333dc8336274c13cd84d718aea5141cf704aef3ac5d6a48f/head?size=512
    Example output for /head/{player}
  4. GET

    /bust/{player}

    3D bust: head, torso and arms.

    size
    Output width in px, 16–1024. Default 256.
    overlay
    Set to false to hide outer layers.
    style
    flat for the 2D front view.
    https://mccatalog.com/texture/6c38aba62a532aa0333dc8336274c13cd84d718aea5141cf704aef3ac5d6a48f/bust
    Example output for /bust/{player}
  5. GET

    /body/{view}/{player}

    3D full body. View is front, back, left or right.

    view
    front | back | left | right
    size
    Output width in px, 16–1024. Default 256 (height is 2× width).
    overlay
    Set to false to hide outer layers.
    style
    flat for the 2D pixel view.
    https://mccatalog.com/texture/6c38aba62a532aa0333dc8336274c13cd84d718aea5141cf704aef3ac5d6a48f/body-front?size=320
    Example output for /body/{view}/{player}
  6. GET

    /raw/{player}

    Raw 64×64 skin texture. Legacy 64×32 skins are upgraded automatically.

    https://mccatalog.com/texture/6c38aba62a532aa0333dc8336274c13cd84d718aea5141cf704aef3ac5d6a48f/raw
    Example output for /raw/{player}
  7. GET

    /cape/{player}

    Outer side of the player's cape. Uses the custom OptiFine cape when there is one, otherwise the Mojang cape. 404 when the player has neither.

    size
    Output width in px, 10–1024. Default 160 (height is 1.6× width).
    source
    optifine | mojang | auto (default).
    style
    raw for the full cape texture, padded to 64×32 or a multiple, ready for skinview3d.
    https://mccatalog.com/cape/Skeppy?size=200
    Example output for /cape/{player}
  8. GET

    /texture/{hash}/{render}

    Render any skin texture hosted on textures.minecraft.net by its hash, as used by the skin library. Render is face, head, bust, body-front, body-back, body-left, body-right or raw.

    hash
    64 hex characters from a textures.minecraft.net URL.
    model
    slim | classic. Inferred from the texture when omitted.
    size
    Output width in px, same limits as the player renders.
    download
    Set to 1 to receive the PNG as a download.
    https://mccatalog.com/texture/6c38aba62a532aa0333dc8336274c13cd84d718aea5141cf704aef3ac5d6a48f/bust?size=200&model=classic
    Example output for /texture/{hash}/{render}

Use it in React

Renders are plain PNGs, so a normal image tag is all you need. This component falls back to another skin service if a render fails. A fuller version with head, face and body variants ships in the repository under examples/SkinRender.tsx.

SkinBust.tsx
"use client";

import { useState } from "react";

export function SkinBust({ uuid, height, username }: { uuid: string; height: number; username?: string }) {
  const [failed, setFailed] = useState(false);
  const width = Math.round(height * 0.8);
  return (
    <img
      key={failed ? "fallback" : "primary"}
      src={failed
        ? `https://crafthead.net/armor/bust/${uuid}/${width}`
        : `https://mccatalog.com/bust/${uuid}?size=${width * 2}`}
      onError={() => setFailed(true)}
      alt={username ? `${username} skin` : ""}
      width={width}
      height={height}
      loading="lazy"
      draggable={false}
    />
  );
}