Embedding & Shortcodes

Once you have a shortcode, embedding a render is usually a single line of HTML or Markdown. This page collects the most common patterns and the things that trip people up.

What's a shortcode?

A shortcode is a 6-character ID (e.g. abc123) that refers to a saved scene — all the poses, props, lighting, and camera settings you composed in the Studio. Shortcodes are the unit of reuse: one shortcode plus one or more player identifiers produces a render.

A shortcode never changes. Once you have one, you can render it any number of times, with any players, and the result is deterministic.

Getting a shortcode

Two paths:

• From the Studio — compose any scene, then click Share. You get a shortcode back immediately.
• From a public template — browse /api/templates or the in-Studio gallery and use any shortcode you find. Anything in the gallery is fair game to embed.

The Sharing section of the Studio docs covers the Share flow end to end.

URL shape

Every embed is a URL of this form:

https://minecraftrender.com/api/render/{gamertags}/{shortcode}?format=webp

• {gamertags} — a comma-separated list of player identifiers, one per slot the template expects.
• {shortcode} — the 6-character ID.
• ?format=webp (default) or ?format=png — controls the returned image format.

Examples:

https://minecraftrender.com/api/render/Dinnerbone/abc123
https://minecraftrender.com/api/render/.MyGen/abc123
https://minecraftrender.com/api/render/Dinnerbone,.MyGen/xyz789?format=png

See Player identifiers for the full rules on Java vs Bedrock formats.

HTML

The default embed is a plain <img>:

<img
  src="https://minecraftrender.com/api/render/Dinnerbone/abc123"
  alt="Dinnerbone's rendered skin"
  loading="lazy"
  width="512"
  height="512">

Notes:

• loading="lazy" is worth it — renders are roughly 40–120 KB of WebP each, and lazy loading means users only pay for images they actually scroll to.
• Give width and height (or CSS dimensions) so the browser reserves layout space before the image arrives. Otherwise the page jumps when the render lands.
• Renders aren't square. Each template has its own aspect ratio, but it's not always exact to the pixel — Persona characters with big hair, chunky outfits, or long capes can push the silhouette and shadow footprint outward, which nudges the output dimensions from one player to the next. Reserve layout space generously (aspect-ratio or a min-height) rather than assuming a fixed pixel size.

CSS background

.profile-banner {
  background-image: url("https://minecraftrender.com/api/render/.MyGen/abc123?format=png");
  background-size: cover;
}

Either format preserves the transparent background the renderer produces — pick PNG if you want the widest compatibility, WebP for smaller files.

<picture> with PNG fallback

Overkill for most use cases — WebP is supported everywhere that matters — but if you're targeting genuinely ancient browsers:

<picture>
  <source type="image/webp" srcset="https://minecraftrender.com/api/render/Dinnerbone/abc123">
  <img src="https://minecraftrender.com/api/render/Dinnerbone/abc123?format=png" alt="">
</picture>

Markdown

Standard image syntax:

![Dinnerbone](https://minecraftrender.com/api/render/Dinnerbone/abc123)

Works in GitHub READMEs, issue descriptions, PR bodies, MkDocs, Docusaurus, and anywhere else Markdown renders images.

Forum BBCode

Most forums (phpBB, MyBB, XenForo, vBulletin) accept BBCode image tags:

[img]https://minecraftrender.com/api/render/.MyGen/abc123[/img]

If the forum has a signature size cap, pick a template with a compact aspect ratio (half-body portrait rather than full-scene) so your signature fits under the limit.

Discord

Two patterns work in Discord:

Auto-unfurl

Paste a render URL directly into a message and Discord unfurls it as an inline image. Simplest possible integration — no bot needed.

Webhook / bot embed

If you're posting from a bot or webhook, put the render URL into an embed's image.url:

{
  "embeds": [{
    "title": "Welcome, MyGen!",
    "image": {
      "url": "https://minecraftrender.com/api/render/.MyGen/abc123"
    }
  }]
}

Discord caches embed images aggressively on its own CDN, so the same URL won't hit MinecraftRender again for quite a while once Discord has seen it.

OBS & streaming overlays

Add a Browser source in OBS / Streamlabs pointing at the render URL. The browser source will load the image and render it at the native aspect ratio of the template — renders are always transparent-backgrounded, so the character sits cleanly on top of whatever's behind the source.

https://minecraftrender.com/api/render/.MyStreamerName/abc123?format=png

For a "character in the corner" overlay, pick a template with a portrait-style camera framing and tight cropping. Because the render is a static image, you can set the browser source to a small width/height and scale it with CSS in the source's custom CSS field.

Thumbnails for lists

If you're building a gallery-style UI listing many templates, don't use the render endpoint for thumbnails — that fires a real render (or cache hit) for every tile. Use the dedicated thumbnail endpoint instead:

https://minecraftrender.com/api/templates/{shortcode}/thumbnail

Thumbnails are pre-baked at around 360p, cached for 24 hours client-side, and use a generic Steve / Persona character rather than any specific player. They're perfect for grid previews, link cards, and anywhere a tiny representative image will do.

Switch to a real render URL only when the user picks a template and wants to see it with their own skin.

Dynamic / per-user renders

For a site that renders each visitor's own player (forum avatars, profile pages, leaderboards), build the URL on the server with the user's stored identifier:

<img src="https://minecraftrender.com/api/render/{{ user.gamertag }}/abc123" alt="">

Tips:

• Pick one shortcode and reuse it across the whole feature — that way every user's render lives at a predictable URL and the cache works for you. Switching templates per user defeats caching and slows your pages.
• URL-encode the player identifier if it might contain anything other than letters, digits, dots, and dashes. In practice only Bedrock gamertags with spaces need this — .My Gen → .My%20Gen.
• Store the canonical ID (UUID for Java, XUID for Bedrock) rather than the mutable display name, if your app already knows it. Java usernames can change; UUIDs can't.

Cache warming

Because the same (template, player, format) tuple shares a cache entry, the first render for a given user is slow (maybe a few seconds) and subsequent ones are fast (tens of milliseconds). If you want to avoid the first-render delay on user-facing pages, fire a warm-up request server-side when the user signs up or updates their profile.

Common gotchas

Forgetting the Bedrock prefix

If you write /api/render/MyGen/abc123 instead of /api/render/.MyGen/abc123, the server treats MyGen as a Java username and returns 404 because no such Java player exists. Numeric XUIDs are auto-detected without the prefix, but anything alphabetic needs the leading ..

Wrong number of players

The template's playerCount is fixed. Pass too few or too many gamertags and you get a 400. If you're not sure how many a template expects, hit GET /api/templates/:shortcode and read playerCount.

URL-encoding

Gamertags with spaces must be URL-encoded. .My Gen becomes .My%20Gen. Most HTTP clients and template engines do this for you — make sure yours does.

CORS on JSON endpoints

Loading images via <img> or CSS works from any origin. But fetching JSON endpoints (templates, template metadata) from browser JavaScript on another origin will be blocked by the browser's same-origin policy — proxy those through your own backend. See Conventions.

Serving from your own CDN

If you front render URLs with your own CDN (Cloudflare, Fastly, etc.), you'll get cache hits on the CDN side as well as ours — but don't set an aggressive CDN TTL on the JSON endpoints (template metadata, template list) or you'll serve stale data after someone edits a template.