Getting started with the Minecraft block render API

How to render any Minecraft block or item as a PNG from one URL: identifiers, the two endpoints, first examples, caching and error handling. No key needed.

Your first request

There is nothing to sign up for and nothing to install. Ask for a block by name and you get a PNG:

https://blockrender.dev/render/block/grass_block.png

The .png is optional. /render/block/grass_block is the same request, resolves to the same cache entry and answers with the same ETag; the extension exists because forum tags, webhooks and site builders often refuse a URL that does not end in an image name.

Drop it in an img tag and you are done:

<img src="https://blockrender.dev/render/block/grass_block.png?size=128" width="128" height="128" alt="Grass block">

Identifiers

An identifier is a Minecraft id. All of these reach the same block:

• grass_block — the normal form.
• minecraft:grass_block — the namespace is accepted and ignored; only vanilla assets exist here.
• Grass-Block and grass block — case, hyphens and spaces are normalised.

An id nobody has is a 404 in plain text with a short list of near misses, so a typo tells you what you meant rather than just failing.

Unknown block "grss_block". Did you mean: grass_block, gray_wool?

Blocks and items are two endpoints

/render/block/<id> rasterises the block's own model, in the state it rests in when you place it. /render/item/<id> draws the item: for most items that is the 16×16 sprite, scaled with square pixels; for an item the game draws as a block, it is the same isometric render the inventory shows.

For a full cube the two are identical. For anything with a shape they are not — a fence block is a post, a fence item is the inventory model; stairs face differently. Pick the one that matches what you are illustrating. Blocks and items goes through every case.

Options

Everything else is a query parameter. The ones you will reach for first:

• size — height in pixels, 8 to 1024. The canvas is square unless you give width or height.
• view — iso (default), front, back, side, top, bottom.
• yaw and pitch — the camera, in degrees, when a named view is not the angle you want.
• bg — a hex colour behind the render. Transparent by default.
• fit=block — frame the whole 16×16×16 cube, so a torch stays small next to a full block.
• biome — which biome's colour tints grass, leaves and water. Plains by default.
• download=1 — send it as an attachment.

https://blockrender.dev/render/block/oak_leaves.png?size=512&biome=swamp&bg=1e1e2e

The parameter reference lists every one with its range and default, and the playground builds the URL by clicking.

The JSON catalogue

/api/blocks and /api/items return every id with its display name and category — 1,102 blocks and 1,473 items in Minecraft 26.2. /api/block/<id> adds the resolved model, the textures it draws with, their average and dominant colours, and the biome tint if it has one.

const res = await fetch('https://blockrender.dev/api/block/grass_block');
const { name, colours, textures } = await res.json();

console.log(name);              // "Grass Block"
console.log(colours.dominant);  // "#5d8f3c"
console.log(textures[0].url);   // "/texture/block/dirt.png"

Errors

Errors are plain text with a real status code, never a PNG of the word "error". A 400 means a parameter was wrong and says what was expected; a 404 means the id does not exist in this version, or exists but has no model the renderer can use — chests, banners, beds and a few dozen others are drawn by the game itself and are honestly reported as such.

Where to next

• Blocks & items: Which state of a block gets rendered, why an item is sometimes a sprite and sometimes a cube, how biome tints are applied and which assets have no model at all.
• Parameters: Every query parameter of the Minecraft block and item render API: size, view, camera yaw and pitch, zoom, background, shading and biome tint, from the code.
• Examples: Copy-paste recipes: inventory icons, wiki-style isometric renders, item sprites for a shop GUI, transparent thumbnails, and the JSON catalogue in a script.
• Caching & limits: How Block Render caches models and PNGs, which response headers to rely on, the size limits, how ETags make a repeat request free, and every error code.
• Minecraft block PNG: Transparent isometric renders of any block, at 64 to 1024 pixels, straight from a URL.
• Minecraft item PNG: Item sprites scaled with crisp pixels instead of a blurry upscale.
• Minecraft block textures: The raw 16×16 texture files behind every block, and how they turn into a render.
• mcasset.cloud alternative: A texture browser that also renders, and answers from a URL rather than a single-page app.
• /llms.txt: the whole API as one plain-text file, for models and their agents.