Minecraft 프로필 API

코드 예제

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

JavaScript (브라우저 또는 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 (터미널)

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_"

모든 엔드포인트

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

프로필 검색

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

매개변수

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

플레이어 머리 이미지

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.

스킨 & 망토 URL

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.

소셜 링크 & 최근 검색

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

응답 형식

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 }

HTTP 상태 코드 & 일반 오류

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

속도 제한

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

전체 예제

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

JavaScript (브라우저 또는 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' }; }
}

자주 묻는 질문

Common questions about the Minecraft Profile API.

사용 사례

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

• Discord 봇
• 웹 앱
• 서버 플러그인
• Minecraft 도구

다음 단계

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.