API de Profils Minecraft

Exemples de Code

Same request, different languages. Replace jeb_ with any Minecraft username. Each example fetches the profile and reads the UUID.

JavaScript (navigateur ou Node.js)

fetch() sends the request. res.json() parses the JSON. data.java?.uuid gets the Java UUID (or data.bedrock?.xuid_decimal for Bedrock).

// 1. Send GET request to the API
const res = await fetch('https://vrc.lol/api?username=jeb_');
// 2. Parse JSON response
const data = await res.json();
// 3. Use the data — Java UUID or Bedrock XUID
if (data.success) console.log(data.java?.uuid ?? data.bedrock?.xuid_decimal);

Python

requests.get() fetches the URL. .json() parses the response. data['java']['uuid'] gets the UUID. Install with pip install requests.

import requests

# 1. GET request — returns JSON
data = requests.get('https://vrc.lol/api?username=jeb_').json()
# 2. Check success and extract UUID
if data.get('success'):
    uuid = data.get('java', {}).get('uuid') or data.get('bedrock', {}).get('xuid_decimal')
    print(uuid)

PHP

file_get_contents() fetches the URL. json_decode(..., true) parses JSON into an array. $data['java']['uuid'] gets the UUID.

// 1. Fetch URL and parse JSON
$data = json_decode(file_get_contents('https://vrc.lol/api?username=jeb_'), true);
// 2. Get UUID (Java or Bedrock)
if ($data['success'] ?? false) {
    $uuid = $data['java']['uuid'] ?? $data['bedrock']['xuid_decimal'] ?? '';
    echo $uuid;
}

cURL (terminal)

Run this in your terminal. The JSON is printed to stdout. Pipe to jq for pretty output: curl "..." | jq.

curl "https://vrc.lol/api?username=jeb_"

Tous les Endpoints

Quick reference. Base URL: https://vrc.lol

Recherche de Profil

One URL returns UUID, skin, cape, and name history. Pass username, UUID, or XUID.

Paramètres

See Code Examples above for JavaScript, Python, PHP, and cURL.

Image de Tête du Joueur

64×64 PNG of a player's face. Use the URL directly in an <img> tag — no API call needed.

HTML — put URL in img src

The browser fetches the image directly. No JavaScript needed.

<img src="https://vrc.lol/head?username=Notch&size=64" alt="Notch" />

Python — save head as PNG

r.content is the raw PNG bytes. Write to a file.

import requests
r = requests.get('https://vrc.lol/head?username=Notch&size=64')
with open('head.png', 'wb') as f: f.write(r.content)

Params: username, uuid, size (8–512), format (png|webp)

Recommended sizes: 64px for general use. 80px for Discord embeds. 512px for high-res previews. Use format=webp for smaller file size.

URLs Skin & Cape

Direct URLs to skin or cape PNG. Use in browsers, Discord, or download. CORS enabled.

Use type=java or type=bedrock for skin — Java uses Mojang textures, Bedrock uses Xbox/GeyserMC.

Liens Sociaux & Recherches Récentes

Optional endpoints: site social links and recent lookup statistics. Use ?social=1 or ?recent=1.

Format de Réponse

All endpoints return JSON. Success: success: true + data. Error: success: false + error + code.

Response structure (success)

success

Boolean — true when a profile was found.

java

Object — Java Edition data: username, uuid, skin_url, cape_url, name_history (array of {name, changed_at}).

bedrock

Object — Bedrock data: gamertag, xuid_decimal, floodgate_uuid, skin_url, cape_url.

cached

Boolean — true if served from cache (faster).

name_history format: [{ "name": "jeb_", "changed_at": null }, { "name": "oldname", "changed_at": 1234567890000 }] — changed_at is Unix ms or null for original name.

Success (200) — example for jeb_

{ "success": true, "java": { "username": "jeb_", "uuid": "853c80ef3e3740fdaa867b06307a3d4f", "skin_url": "/skin?username=jeb_&type=java", "name_history": [{ "name": "jeb_" }] } }

Error (404)

{ "success": false, "error": "...", "code": "NOT_FOUND", "status": 404 }

Codes d'État HTTP & Erreurs Courantes

Standard codes. 200 = success. 404 = not found. 429 = rate limited.

Limite de Requêtes

Normal lookups: no limit (cached). Force update (?update=true): 1 hour per IP.

Exemples Complets

Reusable functions that fetch a profile and return UUID. Replace jeb_ with any username.

JavaScript (navigateur ou Node.js)

async function getUuid(username) {
  const res = await fetch(`https://vrc.lol/api?username=${encodeURIComponent(username)}`);
  const data = await res.json();
  if (!data.success) throw new Error(data.error || 'Not found');
  return data.java?.uuid ?? data.bedrock?.xuid_decimal;
}

Python (requires: pip install requests)

import requests

def get_uuid(username):
    data = requests.get(f'https://vrc.lol/api?username={username}').json()
    if not data.get('success'):
        raise Exception(data.get('error', 'Not found'))
    return data.get('java', {}).get('uuid') or data.get('bedrock', {}).get('xuid_decimal')

PHP

function getUuid(string $username): string {
    $data = json_decode(file_get_contents('https://vrc.lol/api?username=' . urlencode($username)), true);
    if (empty($data['success'])) throw new Exception($data['error'] ?? 'Not found');
    return $data['java']['uuid'] ?? $data['bedrock']['xuid_decimal'];
}

Real-world: Name history + error handling

Fetch a profile, show name history, and handle errors (404, network failure).

async function getProfile(username) {
  try {
    const res = await fetch(`https://vrc.lol/api?username=${encodeURIComponent(username)}`);
    const data = await res.json();
    if (!data.success) return { error: data.error || 'Not found' };
    const names = data.java?.name_history?.map(n => n.name) ?? [];
    return { uuid: data.java?.uuid, names };
  } catch (e) { return { error: 'Network error' }; }
}

Questions Fréquentes

Common questions about the Minecraft Profile API.

Cas d'Utilisation

The Minecraft Profile API works for many projects. Common examples:

• Bots Discord
• Applications web
• Plugins serveur
• Outils Minecraft

Prochaines Étapes

Use the API in your project — Profile Lookup for manual lookups, UUID Guide for server setup, JSON Lists for banned-players.json and whitelist. Skin downloads and Cape gallery for textures.