Getting started with the Minecraft skin render API

Anything else, such as a 20-character name or a malformed hash, answers 400 with a plain-text reason.

Render types

Each type has its own default size and aspect ratio. The three 3D types (head, bust, body) accept camera and pose parameters; the flat ones are pixel-exact layouts of the texture.

Aliases: avatar → face, full → body, portrait → bust.

First examples

Drop any of those into an <img>. Add width and height attributes matching the requested size so the page does not shift while the image loads.

<img src="https://skinrender.dev/render/853c80ef3c3749fdaa49938b674adae6/head?size=128"
     width="128" height="128" alt="jeb_" loading="lazy" decoding="async">

Parameters

Parameters are grouped into 7 families. Every one of them is listed in the parameter reference, which is generated from the same table the parser reads.

• Output: Size, background and how the file is delivered.
• Camera: Where the model is viewed from. 3D renders only.
• Model: Which texture and arm width to render.
• Layers: Toggle the second skin layer per body part.
• Lighting: Shading and shadow.
• Pose: Named poses and per-joint rotations, in degrees by default.
• Fallback: What happens when a skin cannot be found.

A few rules apply everywhere:

• Booleans accept 1/0, true/false, yes/no, on/off, or the bare key (?crop means crop=true).
• Angles are degrees unless units=rad, and they wrap rather than error.
• size is the height; width follows the type’s aspect ratio unless width or height is given. Nothing exceeds 1024 px per side.
• Unknown parameters are ignored and listed in the X-Ignored-Params response header. Out-of-range values are a 400.
• Parameter names are case-insensitive and most have short aliases (w, h, bg, rotate…).

Profile JSON

If you need the resolved profile rather than an image, the same identifiers work on the JSON endpoint:

GET https://skinrender.dev/api/profile/Notch

{
  "uuid": "069a79f444e94726a5befca90e38aaf5",
  "name": "Notch",
  "model": "classic",
  "skinUrl": "https://textures.minecraft.net/texture/…",
  "skinHash": "…",
  "capeUrl": null,
  "capeHash": null
}

GET /api/health returns a small JSON status document you can point a monitor at.

Caching advice

Renders are deterministic: the same URL always produces the same bytes. That makes them safe to cache anywhere, and you should.

• Responses carry Cache-Control: public, max-age=3600, stale-while-revalidate=86400; texture-hash and default-skin renders are immutable.
• Every response has an ETag. Send it back as If-None-Match and you get a 304 with no body.
• On our side, profiles are cached for 15 minutes, textures for 24 hours and finished PNGs for an hour in memory. The first request for a player is the slow one (a few hundred milliseconds, because Mojang has to be asked); everything after is served in a few milliseconds.
• If you render the same players over and over, put a CDN or your own cache in front, or fetch once and store the file.

The details, including Mojang’s rate limit on profile lookups, are on the caching and limits page.

Error handling

Errors are plain text with an appropriate status code, never a PNG that looks like an error.

In an <img> you rarely need to handle any of this: with the default fallback a valid URL always yields an image. When you fetch programmatically, check response.ok and read the body as text on failure.

Next steps

• Render types: sizes, aspect ratios and examples per type.
• Poses: named poses, per-joint control and animation frames.
• Examples: profile pictures, Discord embeds, server cards.
• Libraries and snippets: JavaScript, Python, Java, PHP, Go.
• Playground: build a URL by clicking.