# Skin Render — https://skinrender.dev

> A free, keyless Minecraft skin renderer API. One GET returns a PNG of any
> player's face, head, bust or full body, from a username, a UUID or a texture
> hash, with poses, camera angles, layer toggles and capes.

Written for a model helping someone use this API. Everything below is generated
from the source, so it matches the running service. Two things to know before
you write code with it: the URL is the entire interface — there is no key, no
signup and no client library to install — and the same URL always produces the
same bytes, so the answer to "how do I cache this" is usually "you already are".

## Endpoints

- GET https://skinrender.dev/render/<id>/<type>?<options> — image/png
- The type may end in ".png": /body.png is the same request as /body, same cache
  entry and same ETag. Use it where a URL has to look like an image file (forum
  tags, webhooks, site builders). Any other extension is a 400.
- GET https://skinrender.dev/render/<id> — 301 redirect to the body render
- GET https://skinrender.dev/render/mob/<mob>/<body|head>?<options> — image/png, a mob rather
  than a player (see Mobs below). /render/mob/<mob> redirects to the body render.
- GET https://skinrender.dev/api/profile/<id> — application/json: uuid, name, model, skinUrl, skinHash, capeUrl, capeHash.
  "model" is Mojang's own metadata, not the arm width a render picks: model=auto renders slim when the
  texture is a slim one, even if the profile says classic.
- HEAD and OPTIONS work on both. Nothing accepts POST; there is nothing to write.

## Identifiers

- A username: 1-16 letters, digits or underscores, case-insensitive.
- A UUID, with or without dashes.
- texture:<64-hex-hash> (or the bare hash) from textures.minecraft.net — renders
  that exact texture with no profile lookup, and is cached as immutable.
- steve or alex — the default skins.
- /api/profile/ takes only usernames and UUIDs; the other three are not profiles
  and answer 400.

Prefer UUIDs in anything you store: usernames change, UUIDs do not.

## Render types

- face — The 8×8 face with the hat layer on top, scaled with crisp pixels. The classic avatar. Default canvas 256x256, flat.
- head — The head as a 3D cube, lit and angled, with the hat layer. Default canvas 256x256, 3D (camera and pose apply).
- bust — Head, torso and arms from the waist up, posable. Default canvas 256x256, 3D (camera and pose apply).
- body — The full posable player model with every layer and the cape. Default canvas 320x512, 3D (camera and pose apply).
- front — A flat, front-on layout of the whole skin, as skin sites show it. Default canvas 256x512, flat.
- back — The same flat layout seen from behind, cape included. Default canvas 256x512, flat.
- skin — The raw 64×64 texture, upgraded from the legacy 64×32 layout when needed. Default canvas 256x256, flat.
- cape — The front of the profile’s cape, flat. Default canvas 160x256, flat.

size is the height in pixels (8-1024); width follows the type's aspect ratio
unless width or height is given.

## Parameters

Booleans accept 1/0, true/false, yes/no, on/off, or the bare key. Angles are
degrees unless units=rad, and they wrap instead of erroring. Names are
case-insensitive. A parameter that does not apply to the requested type is
ignored and named in the X-Ignored-Params response header; an out-of-range value
is a 400 with a message that says what was expected.

### Output
Size, background and how the file is delivered.

- size (8..1024; default 256 for face/head/bust/skin/cape, 512 for body/front/back; applies to all)
  Height of the image in pixels. Width follows the render type’s aspect ratio unless width is given.
- width (8..1024; default none; applies to all; alias w)
  Explicit width in pixels. Overrides the aspect ratio derived from size.
- height (8..1024; default none; applies to all; alias h)
  Explicit height in pixels. Overrides size.
- bg (hex colour, e.g. 1e1e2e or 1e1e2e80; default none; applies to all; alias background)
  Background colour as 3, 4, 6 or 8 hex digits (with or without #), or transparent.
- aa (1..4; default 2; applies to head, bust, body)
  Supersampling factor for smoother edges. 1 disables anti-aliasing and is fastest. Lowered automatically so that aa² × width × height stays within 4,194,304 (2048×2048) pixels.
- crop (true|false; default false; applies to head, bust, body)
  Trim fully transparent rows and columns from the edges of the finished image. With format=apng every frame is trimmed to the same rectangle, the union of their bounds, so the animation does not jump.
- margin (0..0.45; default 0.05; applies to head, bust, body)
  Fraction of the canvas kept empty around the auto-framed model.
- mirror (true|false; default false; applies to all; alias flip)
  Mirror the finished image horizontally.
- format (png|apng; default png; applies to head, bust, body)
  File format: png is a single still image, apng an animated PNG that plays one loop of the pose. apng needs an animated pose (walk, run, dance or wave), makes frame meaningless and turns fit off unless you ask for it; a .apng ending on the path means the same thing.
- frames (2..60; default 16; applies to head, bust, body)
  How many frames one loop of an animated PNG is sampled at. frames × width × height must not exceed 16,777,216, and aa is lowered automatically so that aa² × frames × width × height stays within 33,554,432.
- fps (1..50; default 20; applies to head, bust, body)
  Playback rate of an animated PNG in frames per second, written into the file to the nearest millisecond.
- loop (0..100; default 0; applies to head, bust, body)
  How many times an animated PNG plays before it stops on the last frame. 0, the default, plays it forever.
- download (true|false; default false; applies to all; alias dl)
  Send the image as an attachment so browsers save it instead of displaying it.
- filename (text; default none; applies to all)
  File name used with download. Letters, digits, dashes and underscores; the .png or .apng ending is added.

### Camera
Where the model is viewed from. 3D renders only.

- yaw (-360..360; default 35; applies to head, bust, body; alias rotate, angle)
  Turn the model about its vertical axis, in degrees. 0 faces the camera; positive turns its right side toward you.
- pitch (-360..360; default 12; applies to head, bust, body; alias tilt)
  Tip the model toward or away from the camera, in degrees. Positive looks down on it from above.
- roll (-360..360; default 0; applies to head, bust, body)
  Rotate the whole image about the viewing axis, in degrees.
- fov (0..120; default 0; applies to head, bust, body; alias perspective)
  Vertical field of view in degrees. 0 is orthographic; 30–50 gives a natural perspective, larger values exaggerate it.
- zoom (0.1..8; default 1; applies to head, bust, body; alias scale)
  Multiplier on the auto-framed size. 2 doubles the model on the canvas.
- offsetX (-2..2; default 0; applies to head, bust, body; alias ox)
  Shift the model horizontally by this fraction of the canvas width.
- offsetY (-2..2; default 0; applies to head, bust, body; alias oy)
  Shift the model vertically by this fraction of the canvas height. Positive moves it down.
- fit (true|false; default true; applies to head, bust, body)
  Auto-frame the posed model so it fills the canvas. With fit=false the camera stays fixed, so animations do not jitter between frames.

### Model
Which texture and arm width to render.

- model (auto|classic|slim; default auto; applies to head, bust, body, front, back; alias variant)
  Arm width. auto follows the profile’s own setting, but renders slim anyway when the texture is a slim one, because a slim texture drawn on classic arms has holes; classic is 4 px wide, slim 3 px.
- skin (text; default none; applies to all; alias texture)
  Render this texture instead of the profile’s skin: a textures.minecraft.net hash or URL.
- cape (true|false; default true; applies to head, bust, body, front, back)
  Draw the profile’s cape when it has one.

### Layers
Toggle the second skin layer per body part.

- overlay (true|false; default true; applies to face, head, bust, body, front, back; alias layers)
  Master switch for the second skin layer (hat, jacket, sleeves and trousers). false hides them all.
- hat (true|false; default true; applies to face, head, bust, body, front, back; alias helmet)
  Show the head overlay layer.
- jacket (true|false; default true; applies to head, bust, body, front, back)
  Show the torso overlay layer.
- leftSleeve (true|false; default true; applies to bust, body, front, back)
  Show the left arm overlay layer.
- rightSleeve (true|false; default true; applies to bust, body, front, back)
  Show the right arm overlay layer.
- leftPants (true|false; default true; applies to body, front, back; alias leftTrousers)
  Show the left leg overlay layer.
- rightPants (true|false; default true; applies to body, front, back; alias rightTrousers)
  Show the right leg overlay layer.

### Lighting
Shading and shadow.

- shading (0..1; default 1; applies to head, bust, body; alias light)
  Strength of the per-face shading that gives the render depth. 0 is flat, 1 matches the in-game inventory look.
- shadow (true|false; default false; applies to body)
  Draw a soft drop shadow under the feet.

### Pose
Named poses and per-joint rotations, in degrees by default.

- pose (default|walk|run|wave|sit|sneak|point|dab|zombie|tpose|cheer|think|flex|salute|dance|punch|shrug|jump; default default; applies to bust, body)
  A named pose. Any explicit joint parameter below overrides that joint of the named pose.
- frame (0..1; default 0; applies to bust, body)
  Phase of an animated pose (walk, run, dance, wave) from 0 to 1. Step it to render the frames of a GIF.
- units (deg|rad; default deg; applies to head, bust, body)
  Unit for every angle parameter: degrees or radians.
- headPitch (-360..360; default 0; applies to bust, body)
  Rotation of the head about its side-to-side axis. Positive swings it forward (limbs) or tips it down (head).
- headYaw (-360..360; default 0; applies to bust, body)
  Twist of the head about its vertical axis.
- headRoll (-360..360; default 0; applies to bust, body)
  Rotation of the head about its front-to-back axis. For arms and legs, positive moves the limb outward, away from the body.
- bodyPitch (-360..360; default 0; applies to bust, body)
  Rotation of the torso about its side-to-side axis. Positive swings it forward (limbs) or tips it down (head).
- bodyYaw (-360..360; default 0; applies to bust, body)
  Twist of the torso about its vertical axis.
- bodyRoll (-360..360; default 0; applies to bust, body)
  Rotation of the torso about its front-to-back axis. For arms and legs, positive moves the limb outward, away from the body.
- leftArmPitch (-360..360; default 0; applies to bust, body; alias leftArm)
  Rotation of the left arm about its side-to-side axis. Positive swings it forward (limbs) or tips it down (head).
- leftArmYaw (-360..360; default 0; applies to bust, body)
  Twist of the left arm about its vertical axis.
- leftArmRoll (-360..360; default 0; applies to bust, body)
  Rotation of the left arm about its front-to-back axis. For arms and legs, positive moves the limb outward, away from the body.
- rightArmPitch (-360..360; default 0; applies to bust, body; alias rightArm)
  Rotation of the right arm about its side-to-side axis. Positive swings it forward (limbs) or tips it down (head).
- rightArmYaw (-360..360; default 0; applies to bust, body)
  Twist of the right arm about its vertical axis.
- rightArmRoll (-360..360; default 0; applies to bust, body)
  Rotation of the right arm about its front-to-back axis. For arms and legs, positive moves the limb outward, away from the body.
- leftLegPitch (-360..360; default 0; applies to bust, body; alias leftLeg)
  Rotation of the left leg about its side-to-side axis. Positive swings it forward (limbs) or tips it down (head).
- leftLegYaw (-360..360; default 0; applies to bust, body)
  Twist of the left leg about its vertical axis.
- leftLegRoll (-360..360; default 0; applies to bust, body)
  Rotation of the left leg about its front-to-back axis. For arms and legs, positive moves the limb outward, away from the body.
- rightLegPitch (-360..360; default 0; applies to bust, body; alias rightLeg)
  Rotation of the right leg about its side-to-side axis. Positive swings it forward (limbs) or tips it down (head).
- rightLegYaw (-360..360; default 0; applies to bust, body)
  Twist of the right leg about its vertical axis.
- rightLegRoll (-360..360; default 0; applies to bust, body)
  Rotation of the right leg about its front-to-back axis. For arms and legs, positive moves the limb outward, away from the body.
- capeAngle (0..90; default 10; applies to bust, body)
  How far the cape swings out from the back, in degrees.

### Fallback
What happens when a skin cannot be found.

- default (auto|steve|alex|none; default auto; applies to all; alias fallback)
  What to render when the player has no custom skin or cannot be found. auto picks Steve or Alex the way the game does; none answers 404 instead.

## Poses

pose=<name> on bust and body renders. 18 names:

- default — Standing still, arms and legs straight.
- walk — Mid-stride walk cycle; use frame to pick the phase.
- run — Wider, faster stride with a slight forward lean.
- wave — Right arm raised and waving.
- sit — Sitting down, legs forward, as on a minecart or chair.
- sneak — Crouched, as when sneaking in game.
- point — Right arm pointing straight ahead.
- dab — The dab.
- zombie — Both arms straight out in front.
- tpose — Arms straight out to the sides.
- cheer — Both arms raised, head tipped back.
- think — Hand at the chin, head tilted.
- flex — Both arms flexed upward.
- salute — Right hand at the brow.
- dance — One arm up, one down, hips turned.
- punch — Right arm thrown forward, torso twisted.
- shrug — Arms out, palms up, head tilted.
- jump — Arms back, legs tucked, as at the top of a jump.

The animated ones (walk, run, wave, dance) take frame=0..1 to pick the phase of the
cycle, which is how you render the frames of a GIF or a sprite sheet. Any joint
can be overridden on top of a pose: headYaw, leftArmPitch, rightLegRoll and so
on, or the shorthand leftArm=45 for its pitch.

## Mobs

GET https://skinrender.dev/render/mob/<mob>/<type> renders a mob instead of a player.
The type is body or head, optionally ending in ".png". There is no
identifier to resolve: a mob is a model in the service, so the name in the path
is the whole subject and the render depends on nothing else.

The camera, output and lighting parameters are the same specifications as above,
parsed by the same code with the same defaults: size, width, height, bg, aa, crop, margin, mirror, download, filename, yaw, pitch, roll, fov, zoom, offsetX, offsetY, fit, shading, shadow, frame, units, format, frames, fps, loop.
Two parameters are per mob, because their accepted values belong to it:

- pose=<name> — every mob answers to default and walk; the rest are its own. A
  pose another mob owns is a 400 listing this mob's, never a wrong picture.
- variant=<name> — a colour or breed of the same rig. The first in the mob's list
  is the default. A mob with no variants rejects the parameter with a 400.

Anything that describes a skin (the layer toggles, cape, capeAngle, model,
default, the per-joint rotations) means nothing to a mob: it is ignored and named
in X-Ignored-Params rather than rejected, so a template that builds player URLs
can be pointed at a mob unchanged. There are no per-joint parameters for mobs —
the rigs differ from mob to mob — so pose is the whole posing interface.

An unknown mob is a 404 listing every mob that exists. Mob renders are immutable:
Cache-Control: public, max-age=31536000, immutable, with an ETag and an X-Mob
header naming the mob and variant that were drawn.

12 mobs, generated from the registry:

- creeper — The one that hisses. Four stubby legs, no arms, and that face. (poses default|walk|hiss|look; variants normal|charged; body aspect 0.5)
  https://skinrender.dev/mobs/creeper/
- zombie — Arms out, knees stiff and the shirt still on: the mob everyone meets first. (poses default|walk|lunge|look; variants normal|husk|drowned; body aspect 0.56)
  https://skinrender.dev/mobs/zombie/
- skeleton — Bare bones on two thin legs, standing as if the bow were still in its hands. (poses default|walk|aim|look; variants normal|wither; body aspect 0.38)
  https://skinrender.dev/mobs/skeleton/
- spider — Eight legs, eight eyes and a body low enough to fit under a slab. (poses default|walk|rear|look; variants normal|cave; body aspect 1.88)
  https://skinrender.dev/mobs/spider/
- enderman — Nearly three blocks of black limbs with two eyes burning at the top. (poses default|walk|scream|carry; variants normal|holding; body aspect 0.33)
  https://skinrender.dev/mobs/enderman/
- slime — A cube of translucent green jelly with a smaller, sadder cube set inside it. (poses default|walk|hop|squash; variants normal|magma; body aspect 1.1)
  https://skinrender.dev/mobs/slime/
- pig — Snout, four trotters and an optional saddle. The friendliest render on the site. (poses default|walk|graze|look; variants normal|saddled; body aspect 1.15)
  https://skinrender.dev/mobs/pig/
- cow — Patched hide, stubby horns and a heavy walk. The mooshroom variant comes with spots. (poses default|walk|graze|look; variants normal|mooshroom; body aspect 0.85)
  https://skinrender.dev/mobs/cow/
- sheep — A fleece on four legs, dyed or freshly sheared, with a face poking out of the wool. (poses default|walk|graze|look; variants white|black|pink|sheared; body aspect 0.87)
  https://skinrender.dev/mobs/sheep/
- chicken — Orange beak, red wattle and two wings that never quite get it off the ground. (poses default|walk|flap; variants white|brown; body aspect 0.74)
  https://skinrender.dev/mobs/chicken/
- wolf — Grey fur, white muzzle and a tail that tells you exactly how the meeting is going. (poses default|walk|sit|look; variants wild|tamed|angry; body aspect 1.07)
  https://skinrender.dev/mobs/wolf/
- villager — Brown robe, folded arms and the biggest nose in the game. Hmm. (poses default|walk|trade|look; variants normal|farmer; body aspect 0.38)
  https://skinrender.dev/mobs/villager/

The gallery is https://skinrender.dev/mobs/, one page per mob under it.

## Responses and caching

- Every response: Access-Control-Allow-Origin: *, an ETag, and Cache-Control.
  Renders are public, max-age=3600, stale-while-revalidate=86400; texture-hash
  and default-skin renders are immutable; profile JSON is max-age=600.
- Send the ETag back as If-None-Match to get a 304 with no body.
- X-Skin-Source says how the identifier resolved; X-Render-Ms is the render time;
  X-Cache is HIT or MISS.
- A player with no skin, or a name nobody owns, renders as Steve or Alex with an
  X-Skin-Fallback header rather than failing. default=none asks for a 404
  instead; default=steve or default=alex forces one.
- Errors are plain text, never a PNG: 400 for a bad identifier or parameter, 404
  when default=none and there is nothing to render, 502 when Mojang is
  unreachable.
- Mojang rate-limits the name lookups behind all of this, so names are cached for
  an hour, profiles for 15 minutes and finished PNGs for an hour.

## Examples

- https://skinrender.dev/render/Notch/face?size=64 — an avatar
- https://skinrender.dev/render/Notch/head?yaw=45&pitch=30 — the isometric head
- https://skinrender.dev/render/jeb_/body?pose=wave&size=512 — a waving full body
- https://skinrender.dev/render/jeb_/skin?size=64&download=1 — the raw 64x64 skin file
- https://skinrender.dev/api/profile/jeb_ — the UUID, the model and the texture hashes
- https://skinrender.dev/render/mob/creeper/body?size=512 — a mob, not a player
- https://skinrender.dev/render/mob/creeper/head?size=64 — the same mob's head as an icon

## Documentation

- [Getting started with the Minecraft skin render API](https://skinrender.dev/docs/): Render a Minecraft skin from one URL: UUID or username, all eight render types, copy-paste examples, caching and error handling. Free API docs, no key.
- [Render types: face, head, bust, body, front, back, skin, cape](https://skinrender.dev/docs/render-types/): Every render type of the Minecraft skin API (face, head, bust, full body, front, back, skin and cape) with its default size, parameters and live example URLs.
- [Parameter reference for the Minecraft skin render API](https://skinrender.dev/docs/parameters/): Every query parameter of the Minecraft skin render API: size, camera yaw and pitch, fov, layers, capes, poses, per-joint angles and fallbacks, from the code.
- [Minecraft skin poses: 18 named poses, joints and animation](https://skinrender.dev/docs/poses/): Every Minecraft skin pose the API renders, from wave and sit to think and dab, with live images, per-joint angles, sign conventions and animation frames.
- [Animation: animated PNG, frames and GIF loops](https://skinrender.dev/docs/animation/): Animate a render: format=apng returns the whole pose cycle as an animated PNG, with frames, fps and loop, and stepping frame yourself still builds a GIF.
- [Mob renders: every mob from one URL](https://skinrender.dev/docs/mobs/): Render any Minecraft mob as a transparent PNG from the /render/mob/ path: body or head, every pose and variant, camera angles, parameters, errors and caching.
- [Examples and recipes for Minecraft skin renders](https://skinrender.dev/docs/examples/): Copy-paste Minecraft skin render examples: profile pictures, Discord bot embeds, forum signatures, server list cards, textures by hash and animation frames.
- [Code snippets: HTML, JavaScript, Python, Java, PHP, Go, curl](https://skinrender.dev/docs/libraries/): Use the Minecraft skin render API from HTML, JavaScript, TypeScript, Python, Java (Bukkit, Paper), PHP, Go and curl, with ETag handling for cheap revalidation.
- [Caching, limits, fallbacks and errors](https://skinrender.dev/docs/caching-and-limits/): How the skin cache works: profiles for 15 minutes, textures for a day, rendered PNGs for an hour. Plus the headers to rely on, Mojang rate limits and errors.

## Guides

- [Minecraft avatar API](https://skinrender.dev/minecraft-avatar-api/): Face renders for profile pictures and player lists, with the hat layer and any size.
- [Minecraft head render](https://skinrender.dev/minecraft-head-render/): 3D heads with yaw and pitch, isometric or perspective, for icons and cards.
- [Minecraft body render](https://skinrender.dev/minecraft-body-render/): Full body skin renders with poses, capes and slim or classic arms.
- [Minecraft skin poser](https://skinrender.dev/minecraft-skin-poses/): Pose any skin in 18 named poses or joint by joint, every pose rendered live.
- [Minecraft skin download](https://skinrender.dev/minecraft-skin-download/): Save the raw 64×64 skin file or a cape, and find any player’s skin URL.
- [Minecraft UUID lookup](https://skinrender.dev/minecraft-uuid-lookup/): Username to UUID and back, as JSON your browser code can fetch.
- [Minecraft mob renderer](https://skinrender.dev/minecraft-mob-renderer/): Mobs as transparent PNGs from the same kind of URL, in every pose, variant and angle.
- [Crafatar alternative](https://skinrender.dev/crafatar-alternative/): Every Crafatar and Minotar URL next to the one that replaces it.
- [Mob gallery](https://skinrender.dev/mobs/): every mob rendered live, one page each.

## Notes

- There is no name-history endpoint anywhere in this API; Mojang retired theirs
  in 2022 and the data is not served to anyone.
- The playground at https://skinrender.dev/playground/ builds any of these URLs by
  clicking, which is the fastest way to check an answer before you hand it over.