VZGE is the beautiful Minecraft avatar rendering service.
(Formerly known as SurgePlay Visage)

Running nonstop since 2015 — the original perspective 3D avatar service, trusted by server owners and web designers worldwide. Accept no isometric substitutes!

Redesigned from the ground up to be even faster*, now with support for the Ears mod, capes, 1.19.3 default skins, custom angles, WebP/JPEG-XL support, and clean supersample antialiasing! Read up on the details below.
* Most time spent on renders on the new codebase is waiting for Mojang's API.

Need help or want to chat? Send me an email, join my Discord, or hop in my Matrix space.
Server status can be found here.

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: PatreonCash App — mention VZGE to be included in the tally

Funding Goal

$0
$50
$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!

Important service notice

As of December 3rd 2023, abusive request volume to VZGE with generic User Agents such as Java/17.0.7 has increased to tens of millions per day. Handling this request flood is untenable, and so I have made the decision to block all requests with generic UAs.

If your VZGE client is not using a custom UA, all requests to VZGE will now fail with a 400 error, returning a short explanatory text. You must ensure you use a reasonable User-Agent header in all requests to VZGE, preferably including a link to your website and your email address should you need to be contacted if you are misusing VZGE. An example of such a UA is MyProgramName/2.0 (+https://my.website/myprogramname.html; <me@my.website>).

This mitigation was installed December 9th 2023. CDN fees for the first week of December have exceeded the amount it generally costs to serve VZGE for an entire month. To help mitigate this, I have also been forced to downgrade VZGE from the CDN's normal tier to the "Volume" tier — as a result, the service may now be slower, especially in certain regions.

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:

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: 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.