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机器人
• Web应用
• 服务器插件
• 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.