Support VZGE

VZGE has been running for free since 2015 and gets more popular all the time.
If you can, please support VZGE to pay for hosting costs, CDN fees, and the time I spend working on the code.

Support ($2, $6, or $12/mo) • Sponsor ($24, $36, or $48/mo)
Alternatives: Patreon • Cash App — mention VZGE to be included in the tally

Funding Goal

$48/mo. Updated manually — last update: September 29th 2024

Quick Render

Want an avatar fast? Don't know what an API is? Put your username, UUID, or a Mojang texture ID here!

API

Clicking the various links in this section will dynamically change the sample renders shown below.

Formats

Every render will by default return the best image format that is supported by the browser. This is, from most to least preferred, JPEG-XL, WebP, and PNG. JXL and WebP renders are not lossless — if you want a lossless render, you should explicitly request PNG.

Any format can be requested explicitly by suffixing the render URL with the proper file extension. These are .jxl, .webp, and .png.

Size

Size specifies the height of the render in pixels, not the width. Maximum size for a square render (Face, Front, Head, Bust) is 512. Maximum size for a tall render (Front Full, Full) is 832. The aspect ratio is 8:13 (1.625).

Sizes are rounded to the next multiple of 8 to increase cacheability. You will likely want to request a slightly oversized render for HiDPI support. (Ideally, you would use a <picture> or an img srcset, to save your users' bandwidth. Large renders are not much slower for VZGE to generate due to how the backend works.)

Features

You can disable features by passing ?no=<features>, where <features> is a comma-separated list of one or more of the following:

• shadow — The shadow that shows below Full and Head renders
• cape — The player's cape, if any
• ears — The player's Ears mod features, if any
• helmet — The player's head secondary layer
• overlay — The player's other secondary layers (jacket, sleeves, pants)

Angle

You can adjust the angle for any 3D render by passing e.g. ?y=<yaw>. y is yaw, p is pitch, r is roll. All values are in degrees, and are relative to the default VZGE angle. For Head, the default angle is -35 yaw, -20 pitch. For Bust and Full, it is 20 yaw, -20 pitch. For example, you can flip a Bust/Full render to be facing left by passing ?y=-40. For a Head render, the equivalent is ?y=70.

Angle has no effect on 2D renders, as they are sized so that the edges of the render touch the edges of the image box. As such, any rotation would result in undesirable clipping. Please let me know if you have a use case for rotated 2D renders.

Subjects

Wherever a URL says <subject>, that can be substituted with any of the following:

• A built-in skin:
  • X-Alex
  • X-Ari
  • X-Efe
  • X-Kai
  • X-Makena
  • X-Noor
  • X-Steve
  • X-Sunny
  • X-Zuri
  • X-Ghost (VZGE-specific generic sample skin)
• A username (e.g. unascribed, Falkreon)
  
  Warning: Username lookups are subject to strict ratelimits on Mojang's side. You are strongly encouraged to use UUIDs or texture IDs. Username requests are likely to fail at random. This is also the slowest API, due to the amount of Mojang calls needed.
• A UUID, with or without dashes (e.g. 61699b2ed3274a019f1e0ea8c3f06bc6, e6b5c088-0680-44df-9e1b-9bf11792291b)
  Offline-mode UUIDs will be autodetected and will select the correct default skin.
• A Mojang texture ID (e.g. 3c57f08ff1de1cb2bc116c709881c442830861bf3df7328da72c670225e5eb5a)
  You can find a community gallery of skins by texture ID at mineskin.org. This is the fastest API that retrieves skins.
• A Base64 skin PNG (e.g. iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAABnRSTlMA... )
  Both standard and URL-safe Base64 are accepted. Obviously, URL-safe is less likely to cause issues.
  
  Warning: VZGE's CDN imposes a fairly restrictive limit on the size of URLs. There are many skins that simply will not fit in this endpoint no matter what you do. Use sparingly, and ideally only for testing.

Note that texture IDs and Base64 PNGs do not have an implied player model. You need to specify ?slim or ?wide to pick one. By default, a wide model will be used.

---

Alright, onto the endpoints:

2D Renders

Face/face/<size>/<subject>

A simple 2D face, with helmet and Ears support.
The helmet is rendered slightly larger than the face. /face/256/X-Ghost

Front/front/<size>/<subject>

A square waist-up flat render of the player. /front/256/X-Ghost

Front Full/frontfull/<size>/<subject>

A flat render of the entire player. /frontfull/384/X-Ghost

3D Renders

Head/head/<size>/<subject>

Just the player's severed head, with Ears support.
This can look a little creepy; we recommend the Bust endpoint. /head/256/X-Ghost

Bust/bust/<size>/<subject>

A square waist-up render of the player. /bust/256/X-Ghost

Full/full/<size>/<subject>

A render of the entire player. /full/384/X-Ghost

Skins

Skin/skin/<subject>

The player's raw skin, as returned by Mojang with no processing. May be 64x32 or 64x64, helmet may be completely opaque, etc. /skin/X-Ghost

Processed Skin/processedskin/<subject>

The player's processed skin — the same steps performed by the vanilla client. Namely:

• 64x32 skins are converted to modern 64x64 skins
• Any translucency on the base layers is removed
• Fully-opaque overlays are erased

Well-formed modern skins will appear unchanged. A good example of this processing is Notch's extremely legacy and ill-formed skin, or a skin with Ears Alfalfa data.

/processedskin/X-Ghost

Privacy, Terms, etc

VZGE retains request logs (without IPs) indefinitely, which is used to calculate general metrics on the performance and popularity of the service. This data will never be shared. Error logs are retained for up to a week.

No cookies are set. IPs are retained by our CDN, bunny.net, for up to 3 days. These IPs are used for detecting and dealing with abuse. Referrer information is also monitored for abuse; abusive or excessive request volume will likely result in me politely reaching out to you based on user agent or referrer.

I run VZGE for free! Please be respectful of that. If you're bulk-requesting renders, wait at least a second between subsequent requests. Use loading="lazy" or other lazy loading techniques on large webpages. If you're for-profit, please consider sending in a monthly donation for your usage of VZGE. Large users who are not donating and do not respond to attempts at contact will likely be blocked without warning. A donation is not payment for a service and does not guarantee preferential treatment.

The /skin and /processedskin endpoints are very easy to provide; if you can, it is preferable to use one of those and chop up the skin yourself for face renders. Skin requests will likely never be blocked or ratelimited.

VZGE (the Service) is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Service or the use or other dealings in the Service.

Renders output from this service are provided to you under the CC0 Public Domain Dedication, meaning you may use, redistribute, transform, or anything else as you wish without restriction. This license does not apply to the skin used to create the render — it is your responsibility to ensure you have permission to use a skin.