mirror of
https://github.com/azures04/crafatar.git
synced 2026-03-21 23:41:18 +01:00
269 lines
13 KiB
Plaintext
269 lines
13 KiB
Plaintext
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<title>Crafatar – A blazing fast Minecraft avatar API</title>
|
||
<meta charset="utf-8">
|
||
<link rel="icon" sizes="16x16" type="image/png" href="/favicon.png">
|
||
<%# FIXME: Use CDN %><link rel="stylesheet" href="/stylesheets/bootstrap.min.css">
|
||
<link rel="stylesheet" href="/stylesheets/style.css">
|
||
<meta name="description" content="A blazing fast Minecraft avatar API with support for avatars, skins, and 3D renders!">
|
||
<meta name="keywords" content="minecraft, avatar, renders, skins, uuid">
|
||
<meta name="viewport" content="initial-scale=1, maximum-scale=1">
|
||
<meta name="copyright"content="Crafatar">
|
||
<meta name="language" content="en-US">
|
||
<meta name="robots" content="index">
|
||
<meta property="og:title" content="Crafatar">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="<%= domain %>">
|
||
<meta property="og:image" content="<%= domain %>/logo.png">
|
||
<meta property="og:description" content="blazing fast Minecraft avatar API with support for avatars, skins, and 3D renders!">
|
||
<meta property="og:determiner" content="a">
|
||
<meta property="og:locale" content="en_US">
|
||
<meta name="twitter:card" content="summary">
|
||
<meta name="twitter:creator" content="@Crafatar">
|
||
<script src="/javascript/crafatar.js"></script>
|
||
</head>
|
||
<body lang="en-US">
|
||
<a href="https://github.com/crafatar/crafatar" target="_blank" class="forkme">Fork me on GitHub</a>
|
||
<a href="https://akliz.net/crafatar" target="_blank" title="Crafatar is sponsored by Akliz" class="sponsor">
|
||
<img src="/images/akliz.png" alt="Akliz"></a>
|
||
<div class="jumbotron">
|
||
<div class="container">
|
||
<h1>Crafatar</h1>
|
||
<h2>A blazing fast API for Minecraft faces!</h2>
|
||
|
||
<div id="avatar-wrapper">
|
||
<%# These are shuffled by JS %>
|
||
<div title="jomo's avatar" class="avatar jomo"></div>
|
||
<div title="jake_0's avatar" class="avatar jake_0"></div>
|
||
<div title="sk89q's avatar" class="avatar sk89q"></div>
|
||
<div title="md_5's avatar" class="avatar md_5"></div>
|
||
<div title="notch's avatar" class="avatar notch"></div>
|
||
<div title="jeb's avatar" class="avatar jeb"></div>
|
||
<div title="dinnerbone's avatar" class="avatar dinnerbone flipped"></div>
|
||
<div title="ez' avatar" class="avatar ez"></div>
|
||
<div title="grumm's avatar" class="avatar grumm flipped"></div>
|
||
<div title="themogmimer's avatar" class="avatar themogmimer"></div>
|
||
<div title="searge's avatar" class="avatar searge"></div>
|
||
<div title="xlson's avatar" class="avatar xlson"></div>
|
||
<div title="krisjelbring's avatar" class="avatar krisjelbring"></div>
|
||
<div title="minecraftchick's avatar" class="avatar minecraftchick"></div>
|
||
<div title="kappe's avatar" class="avatar kappe"></div>
|
||
<div title="marc's avatar" class="avatar marc"></div>
|
||
<div title="mollstam's avatar" class="avatar mollstam"></div>
|
||
<div title="evilseph's avatar" class="avatar evilseph"></div>
|
||
<div title="thinkofdeath's avatar" class="avatar thinkofdeath"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="container">
|
||
<section id="documentation">
|
||
<div id="alerts">
|
||
<div class="alert alert-danger" role="alert">
|
||
<h5>Usernames are deprecated!</h5>
|
||
You should only use usernames for <i>testing</i>.<br>
|
||
Updates are slower, some features are not available, and it may <strong>break anytime</strong>!<br>
|
||
<i>We strongly advise you to use UUIDs instead of usernames.</i> <small><a href="#usernames">more info</a></small>
|
||
</div>
|
||
</div>
|
||
|
||
<section id="try">
|
||
<h2><a href="#try">Try it</a></h2>
|
||
<form id="tryit" action="#">
|
||
<div class="row">
|
||
<div class="col-md-11">
|
||
<input id="tryname" type="text" placeholder="Enter valid username or UUID">
|
||
</div>
|
||
<div class="col-md-1">
|
||
<input type="submit" value="Go!">
|
||
</div>
|
||
</div>
|
||
</form>
|
||
</section>
|
||
|
||
<section id="avatars">
|
||
<h2><a href="#avatars">Avatars</a></h2>
|
||
<div class="row">
|
||
<div class="col-md-2">
|
||
<img class="tryit" data-src="/avatars/$?size=100" src="/avatars/853c80ef3c3749fdaa49938b674adae6?size=100" alt="avatar">
|
||
</div>
|
||
<div class="col-md-10">
|
||
<div class="code">
|
||
<%= domain %>/avatars/<mark class="green">uuid</mark>
|
||
</div>
|
||
<p>Accepted <a href="#meta-parameters">parameters</a>: <i><b>size</b>, <b>helm</b>, <b>default</b></i>.</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="head-renders">
|
||
<h2><a href="#head-renders">Head Renders</a></h2>
|
||
<div class="row">
|
||
<div class="col-md-2">
|
||
<img class="tryit" data-src="/renders/head/$" src="/renders/head/853c80ef3c3749fdaa49938b674adae6" alt="head">
|
||
</div>
|
||
<div class="col-md-10">
|
||
<div class="code">
|
||
<%= domain %>/renders/head/<mark class="green">uuid</mark>
|
||
</div>
|
||
<p>Accepted <a href="#meta-parameters">parameters</a>: <i><b>scale</b>, <b>helm</b>, <b>default</b></i>.</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="body-renders">
|
||
<h2><a href="#body-renders">Body Renders</a></h2>
|
||
<div class="row">
|
||
<div class="col-md-2">
|
||
<img class="tryit" data-src="/renders/body/$" src="/renders/body/853c80ef3c3749fdaa49938b674adae6" alt="body">
|
||
</div>
|
||
<div class="col-md-10">
|
||
<div class="code">
|
||
<%= domain %>/renders/body/<mark class="green">uuid</mark>
|
||
</div>
|
||
<p>Accepted <a href="#meta-parameters">parameters</a>: <i><b>scale</b>, <b>helm</b>, <b>default</b></i>.</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="skins">
|
||
<h2><a href="#skins">Skins</a></h2>
|
||
<div class="row">
|
||
<div class="col-md-2">
|
||
<img class="tryit" data-src="/skins/$" src="/skins/853c80ef3c3749fdaa49938b674adae6" alt="skin">
|
||
</div>
|
||
<div class="col-md-10">
|
||
<div class="code">
|
||
<%= domain %>/skins/<mark class="green">uuid</mark>
|
||
</div>
|
||
<p>Accepted <a href="#meta-parameters">parameters</a>: <b>default</b></i>.</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section id="capes">
|
||
<h2><a href="#capes">Capes</a></h2>
|
||
<div class="row">
|
||
<div class="col-md-2">
|
||
<img class="tryit" data-src="/capes/$?default=853c80ef3c3749fdaa49938b674adae6" src="/capes/069a79f444e94726a5befca90e38aaf5?default=853c80ef3c3749fdaa49938b674adae6" alt="cape">
|
||
</div>
|
||
<div class="col-md-10">
|
||
<div class="code">
|
||
<%= domain %>/capes/<mark class="green">uuid</mark>
|
||
</div>
|
||
<p>Accepted <a href="#meta-parameters">parameters</a>: <b>default</b></i>.</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<hr>
|
||
|
||
<section id="meta">
|
||
<h2><a href="#meta">Meta</a></h2>
|
||
<p>
|
||
In the examples above, you can generally use usernames instead of <mark class="green">uuid</mark>. However, apart from the special cases <code><a href="/renders/body/0?default=MHF_Steve" target="_blank">MHF_Steve</a></code> and <code><a href="/renders/body/0?default=MHF_Alex" target="_blank">MHF_Alex</a></code> this is discouraged as explained below.<br>
|
||
You can append <code>.png</code> or any other file extension to the URL path if you like to, but all images are PNG.
|
||
</p>
|
||
|
||
<section id="meta-attribution">
|
||
<h3><a href="#meta-attribution">Attribution</a></h3>
|
||
<p>
|
||
Attribution is <strong>encouraged</strong> but not required.<br>
|
||
If you want to show some support for this (free!) service, place a notice like this somewhere:
|
||
<div class="code">
|
||
Thank you to <a href="https://crafatar.com">Crafatar</a> for providing avatars.
|
||
</div>
|
||
</p>
|
||
</section>
|
||
|
||
<section id="meta-parameters">
|
||
<h3><a href="#meta-parameters">URL Parameters</a></h3>
|
||
<p>
|
||
You can tweak images using <a href="https://en.wikipedia.org/wiki/Query_string" target="_blank">query string parameters</a>.<br>
|
||
Example: <code><%= domain %>/avatars/853c80ef3c3749fdaa49938b674adae6<mark class="blue">?</mark><mark class="green">size=4</mark><mark class="blue">&</mark><mark class="green">default=MHF_Steve</mark><mark class="blue">&</mark><mark class="green">helm</mark></code>
|
||
</p>
|
||
<ul>
|
||
<li><b>size</b>: The size of the image in pixels. <code><%= config.avatars.min_size %> - <%= config.avatars.max_size %></code>
|
||
<li><b>scale</b>: The scale factor renders. <code><%= config.renders.min_scale %> - <%= config.renders.max_scale %></code>
|
||
<li><b>helm</b>: Apply the <span title="Also known as 'hat' or 'jacket' or 'helm'">overlay</span> to the avatar. Presence of this parameter implies <code>true</code>.
|
||
<li>
|
||
<b>default</b>: The fallback to be used when the requested image cannot be served. You can use a <span title="Make sure to properly percent-encode this!">custom URL</span> or any <mark class="green">uuid</mark>.<br>
|
||
The option defaults to either <code>MHF_Steve</code> or <code>MHF_Alex</code>, depending on the requested UUID. All usernames default to <code>MHF_Steve</code>.
|
||
</ul>
|
||
</p>
|
||
|
||
<section id="meta-about-uuids">
|
||
<h3><a href="#meta-about-uuids">About UUIDs</a></h3>
|
||
<p>UUIDs may be any valid Mojang UUID in the blank or dashed format.</p>
|
||
<p>Malformed UUIDs are rejected.</p>
|
||
</section>
|
||
|
||
<section id="usernames">
|
||
<h3><a href="#usernames">About Usernames</a></h3>
|
||
<p>
|
||
We <strong>strongly</strong> advise you to use UUIDs instead of usernames! UUIDs never change while usernames do.<br>
|
||
Looking up players by username has officially been deprecated by Mojang ever since UUIDs were introduced.<br>
|
||
Crafatar uses a legacy API to retrieve skins for usernames that updates very slowly.<br>
|
||
Skins come without any details, including whether a player uses the Alex or Steve skin model.<br>
|
||
Additionally, Mojang has stated that this legacy interface may be disabled anytime, causing all requests to fail.
|
||
</p>
|
||
<p>Malformed usernames are rejected.</p>
|
||
</section>
|
||
|
||
<section id="meta-about-caching">
|
||
<h3><a href="#meta-about-caching">About Caching</a></h3>
|
||
<p>Crafatar caches skins for <%= config.caching.local / 60 %> minutes before checking for skin updates.<br>
|
||
Images are cached in your browser for <%= config.caching.browser / 60 %> minutes until a new request to Crafatar is made.<br>
|
||
When you changed your skin you can try clearing your browser cache to see the change faster.</p>
|
||
</section>
|
||
|
||
<section id="meta-cors">
|
||
<h3><a href="#meta-cors">CORS</a></h3>
|
||
<p>Crafatar supports CORS, so you can make AJAX request from other sites!</p>
|
||
</section>
|
||
|
||
<section id="meta-http-headers">
|
||
<h3><a href="#meta-http-headers">HTTP Headers</a></h3>
|
||
<p>
|
||
Responses come with some custom HTTP headers, useful for debugging.<br>
|
||
Please note that these headers are cached by CloudFlare <small>(CF-Cache-Status: HIT)</small>.
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<b>X-Storage-Type</b>: Details about how the requested image was stored on the server
|
||
<ul>
|
||
<li><b>none</b>: No external requests. Cached: User has no skin.</li>
|
||
<li><b>cached</b>: No external requests. Skin cached and stored locally.</li>
|
||
<li><b>checked</b>: 1 external request. Skin cached, checked for updates, no skin downloaded.<br>
|
||
This happens either when the user removed their skin or when it didn't change.</li>
|
||
<li><b>downloaded</b>: 2 external requests. First request or skin changed, skin downloaded.</li>
|
||
<li><b>server error</b>: This can happen, for example, when Mojang's servers are down.<br>
|
||
If possible, a cached image is served instead.</li>
|
||
<li><b>user error</b>: You have done something wrong, such as requesting a malformed uuid.<br>
|
||
Check the response body for details.</li>
|
||
</ul>
|
||
<li>
|
||
<b>X-Request-ID</b>: The internal ID assigned to this request.<br>
|
||
If you think something is wrong with your request, please <a href="#contact">contact us</a> and provide this ID.
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
<section id="contact">
|
||
<h2><a href="#contact">Contact</a></h2>
|
||
<ul>
|
||
<li>Follow us on twitter <a href="https://twitter.com/crafatar" target="_blank">@crafatar</a></li>
|
||
<li>Open an issue <a href="https://github.com/crafatar/crafatar/issues" target="_blank">on GitHub</a></li>
|
||
<li><a href="https://webchat.esper.net/?channels=crafatar" target="_blank">Join us</a> in #crafatar on irc.esper.net</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
<footer>
|
||
<hr>
|
||
<p class="pull-right">Copyright Crafatar <%= new Date().getFullYear() %></p>
|
||
</footer>
|
||
</div>
|
||
</body>
|
||
</html> |