Documentation

API Wiki

Complete reference for all Minecraft Item API endpoints.

ItemsRotating GIFsGUI RenderingPlayer InventoryPlayer ListTooltipsItem + TooltipSetup & Resource PacksStatsItem FormatGUI FormatPlayer Inv FormatColor Codes

Base URL

https://api.minecraftitems.xyz

Items

GET/api/item/:itemName

Render an item or block image

Parameters

itemNamepath— Item ID (e.g., diamond_sword)
sizepath— Size multiplier (e.g., size=4)
rotationpath— Rotation: left or right
bgpath— Background color (e.g., bg=white)
rpquery— Resource pack ID
cmdquery— Custom model data
glintquery— Enchantment glint (true/false)
apiKeyquery— API key (for resource packs)

Example

/api/item/diamond_sword/size=4/left
Returns: PNG image
POST/api/share

Create a shareable item link

Request Body

apiKey*— Your API key
itemName*— Item ID
scale— Size multiplier (default: 1)
rotation— Rotation in degrees
backgroundColor— Hex color or 'transparent'
resourcePackId— Resource pack ID
customModelData— CMD value
glint— Enchantment glint
Returns: JSON with shareable URL

Rotating GIFs

POST/api/item/gif/direct

Generate a rotating item GIF (returns GIF directly)

Request Body

itemName*— Item ID
frames— Number of frames (8-72, default: 36)
speed— Frame delay in ms (20-200, default: 50)
scale— Output size multiplier (1-8, default: 2)
itemScale— Item size (0.1-5.0, default: 1.0)
zoom— Camera distance (5-100, default: 30)
tilt— X-axis tilt (-90 to 90, default: -20)
renderScale— Resolution (128-1024, default: 512)
backgroundColor— 'transparent' or hex color
glint— Enchantment glint (default: false)
resourcePackId— Resource pack ID
customModelData— CMD value
Returns: GIF image
POST/api/item/gif

Generate a rotating item GIF (returns shareable URL)

Request Body

apiKey*— Your API key
itemName*— Item ID
...— Same options as /api/item/gif/direct
Returns: JSON with shareable URL

GUI Rendering

POST/api/gui

Render a chest/container GUI

Parameters

rowsquery— Number of rows (1-6)
scalequery— Scale multiplier (1-10)
rpquery— Resource pack ID

Request Body

title— GUI title text
items*— Object mapping slot index to item

Example

{ "title": "My Chest", "items": { "0": "diamond_sword", "1": "golden_apple" } }
Returns: PNG image
POST/api/gui/share

Create a shareable GUI link

Request Body

apiKey*— Your API key
title— GUI title
items*— Slot items object
rows— Number of rows (default: 6)
scale— Scale (default: 2)
Returns: JSON with shareable URL

Player Inventory

POST/api/gui/player

Render a player inventory screen

Parameters

scalequery— Scale multiplier (1-10)
rpquery— Resource pack ID

Request Body

playerName— Player name for skin
helmet— Helmet item
chestplate— Chestplate item
leggings— Leggings item
boots— Boots item
offhand— Offhand item
inventory— Inventory slots object
hotbar— Hotbar slots object
Returns: PNG image
POST/api/gui/player/share

Create a shareable player inventory link

Request Body

apiKey*— Your API key
...— Same options as /api/gui/player
Returns: JSON with shareable URL

Player List

POST/api/playerlist

Render a server player list

Request Body

players*— Array of player names or objects
max— Max players (default: 100)
ip— Server IP to display
scale— Scale (default: 2)

Example

{ "players": ["Steve", {"name": "Alex", "text": "§6Alex §7[VIP]", "ping": 50}], "ip": "play.server.com" }
Returns: PNG image
POST/api/playerlist/share

Create a shareable player list link

Request Body

apiKey*— Your API key
...— Same options as /api/playerlist
Returns: JSON with shareable URL

Tooltips

POST/api/tooltip

Render an item tooltip

Request Body

itemName*— Item ID
displayName— Custom display name (supports color codes)
rarity— common, uncommon, rare, epic, legendary
lore— Array of lore lines
enchantments— Array of enchantments (e.g., 'Sharpness:5')
unbreakable— Unbreakable flag
scale— Scale (1-10, default: 2)

Example

{ "itemName": "diamond_sword", "displayName": "§6Legendary Blade", "lore": ["§7A powerful sword"], "enchantments": ["Sharpness:5"] }
Returns: PNG image
POST/api/tooltip/share

Create a shareable tooltip link

Request Body

apiKey*— Your API key
...— Same options as /api/tooltip
Returns: JSON with shareable URL

Item + Tooltip

POST/api/itemtooltip

Render item with tooltip side-by-side

Request Body

itemName*— Item ID
displayName— Custom display name
rarity— Rarity level
lore— Array of lore lines
enchantments— Array of enchantments
scale— Scale (default: 2)
glintOverride— Force glint on/off
resourcePackId— Resource pack ID
customModelData— CMD value
Returns: PNG image
POST/api/itemtooltip/share

Create a shareable item+tooltip link

Request Body

apiKey*— Your API key
...— Same options as /api/itemtooltip
Returns: JSON with shareable URL

Setup & Resource Packs

POST/api/setup

Create a new API key

Request Body

username*— Your username
Returns: JSON with API key (save immediately!)
POST/api/setup/resourcepack

Upload a resource pack

Parameters

apiKeyquery— Your API key (required)

Request Body

packName*— Name for your pack
downloadUrl*— URL to download the .zip file
Returns: JSON with pack ID
GET/api/resourcepack/:packId

Check resource pack processing status

Parameters

packIdpath— The pack ID from upload
apiKeyquery— Your API key (required)
Returns: JSON with status

Stats

GET/api/stats

Get API usage statistics

Returns: JSON with stats

Item Format Reference

Items in GUIs and inventories can be specified as a simple string or a detailed object.

Simple Item (string)

"0": "diamond_sword"

Complex Item (object)

"0": {
  "item": "paper",
  "cmd": 123,
  "enchantments": [
    {"name": "sharpness", "level": 5}
  ],
  "glint": true
}

item — Item ID (required)

cmd — Custom model data

enchantments — Array of enchantment objects

glint — Force enchantment glint on/off

GUI Items Format

Full example of a chest GUI request body.

{
  "title": "§6Chest Title",
  "items": {
    "0": "diamond_sword",
    "1": "emerald",
    "10": {
      "item": "paper",
      "cmd": 123,
      "enchantments": [
        {"name": "sharpness", "level": 5}
      ],
      "glint": true
    }
  }
}

title — Optional, supports color codes (§)

items — Object mapping slot index to item

Slot 0 = top-left. For 6 rows: slots 0-53. For 3 rows: slots 0-26.

Player Inventory Format

Full example of a player inventory request body.

{
  "playerName": "Notch",
  "helmet": "diamond_helmet",
  "chestplate": "diamond_chestplate",
  "leggings": "diamond_leggings",
  "boots": "diamond_boots",
  "offhand": "shield",
  "inventory": {
    "0": "diamond",
    "1": { "item": "paper", "cmd": 123 }
  },
  "hotbar": {
    "0": "diamond_sword",
    "4": "golden_apple"
  }
}

playerName — Player name for skin/head display

helmet/chestplate/leggings/boots — Armor slots

offhand — Offhand/shield slot

inventory — Main inventory slots 0-26 (3 rows of 9)

hotbar — Hotbar slots 0-8

Color Codes Reference

Use these codes in display names, lore, titles, and player list text.

§0 Black§1 Dark Blue§2 Dark Green§3 Dark Aqua§4 Dark Red§5 Purple§6 Gold§7 Gray§8 Dark Gray§9 Blue§a Green§b Aqua§c Red§d Pink§e Yellow§f White
§l Bold§o Italic§n Underline§m Strike§r Reset

Try It Out

Test all these endpoints interactively in the Playground.