API de Perfiles Minecraft

Ejemplos de Código

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

JavaScript (navegador o 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_"

Todos los Endpoints

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

Búsqueda de Perfil

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

Parámetros

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

Imagen de Cabeza del Jugador

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 de Skin y Capa

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.

Enlaces Sociales y Búsquedas Recientes

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

Formato de Respuesta

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 }

Códigos de Estado HTTP y Errores Comunes

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

Límite de Peticiones

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

Ejemplos Completos

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

JavaScript (navegador o 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' }; }
}

Preguntas Frecuentes

Common questions about the Minecraft Profile API.

Casos de Uso

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

• Bots de Discord
• Aplicaciones web
• Plugins de servidor
• Herramientas Minecraft

Próximos Pasos

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.