Parameter reference for the Minecraft block render API

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.

21 parameters, all optional, all on the query string of a /render/ URL. This page is generated from the same table the parser reads, so it cannot describe a parameter that does not exist or miss one that does.

text

https://blockrender.dev/render/block/oak_log.png?size=512&view=front&bg=1e1e2e80

Booleans accept 1/0, true/false, yes/no, on/off, or the bare key. Names are case-insensitive. Angles are degrees and wrap rather than erroring. A parameter that does not apply to the endpoint you called is ignored and listed in the X-Ignored-Params response header; an out-of-range value is a 400 whose body says what was expected.

Output

Size, background and how the file is delivered.

size

int

Height of the image in pixels. The canvas is square unless width or height is given.

Default: 256
Range: 8 – 1024
Applies to: blocks and items
Example: size=512

width

int alias: w

Explicit width in pixels. Overrides the square canvas derived from size.

Default: none
Range: 8 – 1024
Applies to: blocks and items
Example: width=400

height

int alias: h

Explicit height in pixels. Overrides size.

Default: none
Range: 8 – 1024
Applies to: blocks and items
Example: height=300

bg

color alias: background

Background colour as 3, 4, 6 or 8 hex digits (with or without #), or transparent. Transparent is the default.

Default: none
Range: hex colour
Applies to: blocks and items
Example: bg=1e1e2e

aa

int

Supersampling factor for smoother edges on the diagonal silhouette of a block. 1 disables it and is fastest. Lowered automatically so that aa² × width × height stays within 4,194,304 pixels.

Default: 2
Range: 1 – 4
Applies to: blocks and items
Example: aa=3

crop

bool

Trim fully transparent rows and columns from the edges of the finished image.

Default: false
Range: true | false
Applies to: blocks and items
Example: crop=true

fit

enum

What the camera frames. model fills the canvas with the block’s own shape; block frames the full 16×16×16 cube instead, so a slab, a torch and a full block all come out at the same scale — what a row of inventory slots looks like.

Default: model
Values: model | block
Applies to: blocks and items
Example: fit=block

margin

number

Fraction of the canvas kept empty around the auto-framed model.

Default: 0.05
Range: 0 – 0.45
Applies to: blocks and items
Example: margin=0.1

mirror

bool alias: flip

Mirror the finished image horizontally.

Default: false
Range: true | false
Applies to: blocks and items
Example: mirror=true

download

bool alias: dl

Send the image as an attachment so browsers save it instead of displaying it.

Default: false
Range: true | false
Applies to: blocks and items
Example: download=true

filename

string

File name used with download. Letters, digits, dashes and underscores; .png is added.

Default: none
Range: text
Applies to: blocks and items
Example: filename=grass-block

Camera

Where the block is viewed from. These apply to blocks and to the items the game draws as blocks; an item drawn as a flat sprite ignores them, because there is no camera in a picture of a sprite.

view

enum

A named camera angle. iso is the inventory and wiki look, 45° round and 30° down; front, back, side, top and bottom are straight-on. yaw and pitch override it.

Default: iso
Values: iso | front | top | side | back | bottom
Applies to: blocks and items
Example: view=front

yaw

number alias: rotate

Turn the block about its vertical axis, in degrees. 0 faces its south side toward you; 45 is the isometric view.

Default: none
Range: -360 – 360
Applies to: blocks and items
Example: yaw=-45

pitch

number alias: tilt

Tip the block toward or away from the camera, in degrees. Positive looks down on it; 30 is the isometric view.

Default: none
Range: -360 – 360
Applies to: blocks and items
Example: pitch=15

roll

number

Rotate the whole image about the viewing axis, in degrees.

Default: 0
Range: -360 – 360
Applies to: blocks and items
Example: roll=15

zoom

number alias: scale

Multiplier on the auto-framed size. 2 doubles the block on the canvas and crops what falls outside.

Default: 1
Range: 0.1 – 8
Applies to: blocks and items
Example: zoom=1.5

offsetX

number alias: ox

Shift the render horizontally by this fraction of the canvas width.

Default: 0
Range: -2 – 2
Applies to: blocks and items
Example: offsetX=0.1

offsetY

number alias: oy

Shift the render vertically by this fraction of the canvas height. Positive moves it down.

Default: 0
Range: -2 – 2
Applies to: blocks and items
Example: offsetY=-0.1

Appearance

Shading and biome tint.

shading

number alias: light

Strength of the per-face shading. 1 is the game’s own table — top 1.0, north and south 0.8, east and west 0.6, bottom 0.5 — and 0 draws every face at full brightness.

Default: 1
Range: 0 – 1
Applies to: blocks and items
Example: shading=0.5

tint

color

Overrides the biome tint on grass, leaves, water and other tinted faces with a hex colour. Untinted faces are unaffected.

Default: none
Range: hex colour
Applies to: blocks and items
Example: tint=5fbd4b

biome

enum

Biome the grass, foliage and water tints are taken from. Plains is the default green.

Default: plains
Values: plains | forest | birch_forest | dark_forest | taiga | snowy_taiga | snowy_plains | jungle | bamboo_jungle | savanna | desert | badlands | swamp | mangrove_swamp | cherry_grove | meadow | grove | windswept_hills | old_growth_pine_taiga | mushroom_fields | lush_caves | ocean | warm_ocean | cold_ocean | nether_wastes | the_end
Applies to: blocks and items
Example: biome=swamp