NekoSkin API · API v1

开放 API 文档

本服务提供 Minecraft 玩家信息查询与皮肤图像渲染，支持 Mojang 正版与 LittleSkin 外置登录。

基础地址 https://api.shizuku.l.cd 版本 v1.0.0 返回格式 JSON / PNG CORS 全开放 鉴权 无需 Key

⚠️ 使用前请先看这里

完全免费：无需注册、无需 API Key，直接调用即可。
有速率限制：按访问 IP 计数，60 秒为一个窗口 —— 普通接口 120 次、图片接口 240 次、批量接口 300 次。
数据有缓存：用户名 → UUID 缓存 1 小时，玩家档案缓存 5 分钟；刚换的皮肤最多 5 分钟后才会刷新出来。

120 普通接口 · 每 60 秒

240 图片接口 · 每 60 秒

300 批量接口 · 每 60 秒

5 min 档案缓存时长

快速开始

三步就能跑起来：记下基础地址 → 挑一个接口 → 复制下面的示例代码。

基础地址

所有接口都挂在这个地址下，下文只写路径部分。

Base URL

https://api.shizuku.l.cd

① curl：查一个玩家并拿到全部信息

bash

curl "https://api.shizuku.l.cd/v1/player/myndlp?pretty=1"

② JavaScript（fetch）

javascript

const BASE = "https://api.shizuku.l.cd";

async function fetchPlayer(name) {
  const url = `${BASE}/v1/player/${encodeURIComponent(name)}?pretty=1`;
  const res = await fetch(url);          // CORS 全开放，浏览器可直接请求
  const json = await res.json();

  if (!json.success) {
    throw new Error(`${json.code}: ${json.message}`);
  }

  const d = json.data;
  console.log(d.name, d.uuid_dashed, d.model);
  console.log("头像：", d.images.avatar.url_128);
  console.log("3D 渲染：", d.images.render.url);
  return d;
}

fetchPlayer("myndlp").catch(console.error);

③ Python（requests）

python

import requests

BASE = "https://api.shizuku.l.cd"

# 查玩家全部信息
r = requests.get(f"{BASE}/v1/player/myndlp", params={"pretty": 1}, timeout=10)
data = r.json()

if not data["success"]:
    raise RuntimeError(f'{data["code"]}: {data["message"]}')

player = data["data"]
print(player["name"], player["uuid_dashed"], player["model"])
print("皮肤原图：", player["images"]["skin"]["url"])

# 下载头像 PNG（图片接口直接返回二进制）
png = requests.get(f"{BASE}/v1/avatar/myndlp/256", params={"bg": "1a1b2e"}, timeout=10).content
open("avatar.png", "wb").write(png)

通用约定

统一响应格式

所有 JSON 接口都返回同一层外壳，业务数据放在 data 里。判断成功请用 success 字段。

json · 成功

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": { },
  "timestamp": 1758100000
}

json · 失败

{
  "code": "not_found",
  "success": false,
  "message": "玩家不存在",
  "data": null,
  "timestamp": 1758100000
}

约定	说明
`?pretty=1`	任意 JSON 接口都能加上它，让返回的 JSON 带缩进，方便调试。传 `0` / `false` 关闭。
CORS	响应头带 `Access-Control-Allow-Origin: *`，浏览器端（含本地 `file://` 调试）可直接跨域调用，支持 `GET` / `POST` / `OPTIONS`。
`?source=`	所有接口都支持：`auto`（默认，先试 Mojang 正版再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）。
玩家名 / UUID	凡是路径里的 `{name}`，都能填玩家名或 32 位 UUID（带不带横线都行）。
图片尺寸	图片接口的尺寸既可以写在路径里（`/v1/avatar/myndlp/128`），也可以写成查询参数（`?size=128`）。

响应头还会带 X-Response-Time（服务端耗时）与 X-Powered-By: NekoSkin-API，便于排查问题。

原版 API 对照表

如果你以前直接调 Mojang 官方接口或者 minotar / crafatar 这类第三方服务，可以按下表把地址平移到本服务，参数与返回结构都做了统一，迁移时基本只需要换域名。

原版 API	说明	本服务的替代接口
`GET https://api.mojang.com/users/profiles/minecraft/{name}`	用户名查 UUID	`GET /v1/uuid/{name}`
`GET https://sessionserver.mojang.com/session/minecraft/profile/{uuid}`	按 UUID 取档案（皮肤 / 披风 / 签名）	`GET /v1/profile/{uuid}`
`POST https://api.mojang.com/profiles/minecraft`	批量查 UUID	`POST /v1/batch`
`https://minotar.net/avatar/{name}/{size}`	第三方头像服务	`GET /v1/avatar/{name}/{size}`
`https://minotar.net/body/{name}/{size}`	第三方全身图	`GET /v1/body/{name}/{size}`
`https://crafatar.com/renders/body/{uuid}`	第三方 3D 渲染	`GET /v1/render/{name}/{size}`
`LittleSkin POST /api/yggdrasil/api/profiles/minecraft`	外置登录查 UUID	`GET /v1/uuid/{name}?source=littleskin`

表格里的第三方图片服务（minotar / crafatar）只是对照参考，与本服务没有从属关系。

✨ 本服务在此之上做了聚合与增强

一次请求拿到全部信息：官方要「查 UUID → 取档案 → 解码签名」三步，这里 /v1/player/{name} 一步到位，连所有图片地址都拼好了。
多了服务端 3D 渲染：官方与多数第三方服务只给 2D 拼接头像，本服务额外提供 /v1/render（可旋转的 3D 立体图）与 /v1/cube（等轴测方块）。
支持多数据源：Mojang 正版与 LittleSkin 外置登录用同一套路径，靠 ?source= 切换，auto 会自动回退。
有缓存与限流保护：热门玩家直接命中缓存（快且不打扰上游），同时按 IP 限流防止滥用，见下一节。

速率限制与缓存

限流按访问 IP 计算，窗口固定 60 秒；缓存由服务端统一处理，你不需要做任何额外操作。

速率限制

接口分组	包含接口	额度	窗口
普通 JSON 接口	`/v1/player、/v1/uuid、/v1/profile、/v1/decode、/v1/me、/v1/me/profiles`	120 次	60 秒
图片接口	`/v1/avatar、/v1/head、/v1/body、/v1/render、/v1/cube、/v1/skin、/v1/cape`	240 次	60 秒
批量接口	`/v1/batch`	300 次	60 秒
状态 / 数据源	`/v1/status、/v1/sources`	不计入配额	—

超限时返回 HTTP 429 + code: "rate_limited"，并带上 Retry-After 头告诉你等多久。

限流响应头

响应头	含义
`X-RateLimit-Limit`	当前接口分组的窗口额度上限（普通 120 / 图片 240 / 批量 300）
`X-RateLimit-Remaining`	本窗口内你还能请求多少次，剩余为 0 时下一次就会 429
`X-RateLimit-Reset`	当前窗口结束的 Unix 时间戳（秒），到点后额度重置
`Retry-After`	仅超限时出现，建议等待的秒数

缓存时长

缓存内容	时长	说明
用户名 → UUID	3600 秒（1 小时）	玩家改名不频繁
玩家档案（含皮肤 / 披风地址）	300 秒（5 分钟）	换肤后 5 分钟内自动更新
皮肤贴图二进制	86400 秒（24 小时）	按内容哈希寻址，可长缓存
渲染图（3D 等）	604800 秒（7 天）	跟随贴图哈希，基本等同永久
改名历史	21600 秒（6 小时）	历史记录变化极少

图片响应自带 Cache-Control: public, max-age=…, immutable 与 Access-Control-Allow-Origin: *，浏览器和 CDN 都可以放心缓存。

接口详细文档

共 21 个接口：JSON 接口用于查询数据，图片接口直接返回 PNG，账号接口用于 LittleSkin 外置登录。

JSON 接口

GET

LittleSkin 站点公告

#ls-announcements

/v1/littleskin/announcements

等价写法： GET /v1/littleskin/notice —— 等价写法

中转 LittleSkin 全站公告。正文已做 HTML 白名单清洗（只留 p/ul/li/strong/a 之类），可以直接插进页面。结果缓存 10 分钟。

参数

参数名	类型	必填	默认值	说明
`fresh`	boolean	可选	`0`	传 1 跳过缓存，强制拉取最新公告
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/littleskin/announcements?pretty=1"

# 强制刷新（跳过 10 分钟缓存）
curl "https://api.shizuku.l.cd/v1/littleskin/announcements?fresh=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "source": "littleskin.cn",
    "count": 6,
    "announcements": [
      {
        "id": "05c105df-6cde-4d95-9612-df434810e993",
        "title": "「积分兑换」上新",
        "content": "<p>我们重新推出了「积分兑换」…</p>",
        "color": "cyan",
        "severity": "info",
        "priority": 200,
        "expand": true,
        "timestamp": 1788726139,
        "time_text": "2026-09-07 04:22"
      }
    ]
  }
}

GET

LittleSkin Yggdrasil 元信息

#ls-meta

/v1/littleskin/meta

等价写法： GET /v1/littleskin/yggdrasil —— 等价写法

返回 LittleSkin 的 Yggdrasil API 根地址与 metadata，方便启动器 / 联机工具一键配置外置登录。

参数

参数名	类型	必填	默认值	说明
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/littleskin/meta?pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "api_root": "https://littleskin.cn/api/yggdrasil",
    "auth_url": "https://littleskin.cn/api/yggdrasil/authserver",
    "session_url": "https://littleskin.cn/api/yggdrasil/sessionserver",
    "homepage": "https://littleskin.cn",
    "register": "https://littleskin.cn/auth/register",
    "metadata": {
      "meta": { "serverName": "LittleSkin", "implementationName": "Yggdrasil Connect" }
    }
  }
}

GET

一键获取全部

★ 核心接口 #player

/v1/player/<name>

等价写法： GET /v1/player/{uuid} —— 直接传 UUID 也行 GET /v1/u/{uuid} —— 等价写法

一次请求拿到这个玩家的全部信息：UUID、玩家名、模型类型、皮肤与披风地址，以及所有图片接口的现成地址。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（Minecraft ID），也可以直接传 32 位 UUID（带不带横线都行）
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/player/myndlp?pretty=1"

# 直接传 UUID 也可以
curl "https://api.shizuku.l.cd/v1/player/d5d2a02a769d4f62b62a19d90e79b2d2"

# 只查外置登录（LittleSkin）账号
curl "https://api.shizuku.l.cd/v1/u/d5d2a02a769d4f62b62a19d90e79b2d2?source=littleskin"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "uuid": "d5d2a02a769d4f62b62a19d90e79b2d2",
    "uuid_dashed": "d5d2a02a-769d-4f62-b62a-19d90e79b2d2",
    "name": "myndlp",
    "source": "mojang",
    "model": "slim",
    "model_label": "纤细（Alex）",
    "slim": true,
    "has_skin": true,
    "has_cape": false,
    "skin_url": "https://textures.minecraft.net/texture/410257b0c2651eef...",
    "cape_url": null,
    "skin_hash": "410257b0c2651eef...",
    "cape_hash": null,
    "textures_signed": true,
    "textures_updated_at": 1789652005148,
    "images": {
      "avatar": {
        "url_64": "https://api.shizuku.l.cd/v1/avatar/myndlp/64",
        "url_128": "https://api.shizuku.l.cd/v1/avatar/myndlp/128",
        "url_256": "https://api.shizuku.l.cd/v1/avatar/myndlp/256",
        "sizeable": "https://api.shizuku.l.cd/v1/avatar/myndlp/{size}"
      },
      "head": {
        "url_128": "https://api.shizuku.l.cd/v1/head/myndlp/128",
        "sizeable": "https://api.shizuku.l.cd/v1/head/myndlp/{size}"
      },
      "body": {
        "url": "https://api.shizuku.l.cd/v1/body/myndlp/256",
        "sizeable": "https://api.shizuku.l.cd/v1/body/myndlp/{size}"
      },
      "render": {
        "url": "https://api.shizuku.l.cd/v1/render/myndlp/256",
        "sizeable": "https://api.shizuku.l.cd/v1/render/myndlp/{size}",
        "options": "..."
      },
      "cube": {
        "url": "https://api.shizuku.l.cd/v1/cube/myndlp/256",
        "sizeable": "https://api.shizuku.l.cd/v1/cube/myndlp/{size}"
      },
      "skin": {
        "url": "https://api.shizuku.l.cd/v1/skin/myndlp",
        "download": "https://api.shizuku.l.cd/v1/skin/myndlp?download=1"
      },
      "cape": {
        "url": "https://api.shizuku.l.cd/v1/cape/myndlp",
        "download": "https://api.shizuku.l.cd/v1/cape/myndlp?download=1"
      },
      "isometric": "https://api.shizuku.l.cd/v1/render/myndlp"
    },
    "profile": { "id": "...", "name": "...", "properties": [] },
    "textures": {
      "raw_value": "base64...",
      "raw_signature": "base64...",
      "decoded": { "timestamp": 0, "profileId": "", "profileName": "", "textures": {} }
    },
    "queried_at": "2026-09-17T21:00:00+08:00"
  },
  "timestamp": 1758100000
}

📎 小提示

这是字段最完整的接口，其它 JSON 接口返回的字段都是它的子集。
images 里每条都同时给出「固定尺寸地址」和 sizeable 模板地址：把 {size} 换成想要的分辨率即可（示例中被省略的字段以 ... 占位，实际返回都是完整 URL）。
slim 为 true 表示玩家用的是纤细（Alex）模型；has_cape 为 false 时 cape_url 为 null。

GET

用户名查 UUID

#uuid

/v1/uuid/<name>

按玩家名换取 UUID（同时给出带横线与不带横线两种写法），结果会缓存 1 小时。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（Minecraft ID）
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/uuid/myndlp?pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "id": "d5d2a02a769d4f62b62a19d90e79b2d2",
    "dashed": "d5d2a02a-769d-4f62-b62a-19d90e79b2d2",
    "name": "myndlp",
    "source": "mojang",
    "cached": false
  },
  "timestamp": 1758100000
}

📎 小提示

cached 表示这次结果是否直接命中服务端缓存（true 时响应会更快）。

GET

按 UUID 查档案

#profile

/v1/profile/<uuid>

按 UUID 取回玩家档案：皮肤 / 披风地址、模型类型，以及原始的档案与签名数据。

参数

参数名	类型	必填	默认值	说明
`uuid`	string	必填	`—`	玩家 UUID，32 位十六进制，带横线或不带横线都可以
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/profile/d5d2a02a769d4f62b62a19d90e79b2d2?pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "uuid": "d5d2a02a769d4f62b62a19d90e79b2d2",
    "uuid_dashed": "d5d2a02a-769d-4f62-b62a-19d90e79b2d2",
    "name": "myndlp",
    "source": "mojang",
    "skin_url": "https://textures.minecraft.net/texture/410257b0c2651eef...",
    "cape_url": null,
    "model": "slim",
    "profile": {
      "id": "d5d2a02a769d4f62b62a19d90e79b2d2",
      "name": "myndlp",
      "properties": [
        {
          "name": "textures",
          "value": "eyJ0aW1lc3RhbXAiOjE3ODk2NTIwMDUxNDgsInByb2ZpbGVJZCI6..."
        }
      ]
    },
    "textures": {
      "raw_value": "eyJ0aW1lc3RhbXAiOjE3ODk2NTIwMDUxNDgsInByb2ZpbGVJZCI6...",
      "raw_signature": "base64...",
      "decoded": {
        "timestamp": 1789652005148,
        "profileId": "d5d2a02a769d4f62b62a19d90e79b2d2",
        "profileName": "myndlp",
        "textures": {
          "SKIN": { "url": "http://textures.minecraft.net/texture/410257b0c2651eef..." }
        }
      }
    }
  },
  "timestamp": 1758100000
}

📎 小提示

textures.raw_value 是服务端已经解码过的贴图签名，也可以拿去 /v1/decode 自行验证。

POST

批量查询

#batch

/v1/batch

等价写法： POST /v1/batch —— JSON 请求体 GET /v1/batch?names=a,b,c —— 逗号分隔写法

一次查询多个玩家名或 UUID，最多 100 个；查不到的名字会单独列在 missing 里。

参数

参数名	类型	必填	默认值	说明
`names`	array	可选	`—`	玩家名数组（JSON 请求体）。与 `uuids` 二选一，最多 100 个
`uuids`	array	可选	`—`	UUID 数组（JSON 请求体）。与 `names` 二选一，最多 100 个
`type`	string	可选	`—`	传 `profile` 时返回完整档案，否则只返回 id / dashed / name / source
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

# POST：JSON 请求体（推荐）
curl -X POST "https://api.shizuku.l.cd/v1/batch?pretty=1" \
  -H "Content-Type: application/json" \
  -d '{"names": ["myndlp", "Notch"], "type": "profile"}'

# GET：逗号分隔
curl "https://api.shizuku.l.cd/v1/batch?names=myndlp,Notch&pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "found": [
      {
        "query": "myndlp",
        "id": "d5d2a02a769d4f62b62a19d90e79b2d2",
        "dashed": "d5d2a02a-769d-4f62-b62a-19d90e79b2d2",
        "name": "myndlp",
        "source": "mojang"
      }
    ],
    "missing": ["who_dis"],
    "source": "mojang",
    "count": 1
  },
  "timestamp": 1758100000
}

📎 小提示

超过 100 个名字会返回 too_many_names（HTTP 400）。
批量接口的限流额度更宽松（每 60 秒 300 次），适合做名单同步。

GET

签名解码工具

#decode

/v1/decode?value=<base64>

把 Mojang / LittleSkin 的 textures 签名 value（base64）解成可读 JSON。

参数

参数名	类型	必填	默认值	说明
`value`	string	必填	`—`	base64 编码的 textures value，来自档案里的 `properties[].value`
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/decode?value=eyJ0aW1lc3RhbXAiOjE3ODk2NTIwMDUxNDgsInByb2ZpbGVJZCI6...&pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "decoded": {
      "timestamp": 1789652005148,
      "profileId": "d5d2a02a769d4f62b62a19d90e79b2d2",
      "profileName": "myndlp",
      "textures": {
        "SKIN": { "url": "http://textures.minecraft.net/texture/410257b0c2651eef..." }
      }
    },
    "raw": "{\n  \"timestamp\" : 1789652005148,\n  \"profileId\" : \"d5d2a02a769d4f62b62a19d90e79b2d2\"\n}"
  },
  "timestamp": 1758100000
}

📎 小提示

raw 是解码后未整理的原始字符串，方便你直接校验签名内容。

GET

服务状态

#status

/v1/status

返回服务版本、运行时长、缓存统计与各数据源的健康状态，适合做监控探针。

参数

参数名	类型	必填	默认值	说明
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/status?pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "version": "1.0.0",
    "uptime_ms": 86400000,
    "cache": {
      "enabled": true,
      "entries": 1284,
      "hits": 9021,
      "misses": 1733
    },
    "sources": {
      "mojang": { "enabled": true, "ok": true },
      "littleskin": { "enabled": true, "ok": true }
    }
  },
  "timestamp": 1758100000
}

📎 小提示

该接口只读取本地状态，不请求上游，因此响应极快且不计入限流配额。
页面上还有一个更直观的服务状态页：/status。

GET

数据源列表

#sources

/v1/sources

列出当前可用的数据源及其启用状态，便于前端动态渲染数据源切换器。

参数

参数名	类型	必填	默认值	说明
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/sources?pretty=1"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "sources": [
      { "id": "mojang", "label": "Mojang 官方（正版）", "enabled": true },
      { "id": "littleskin", "label": "LittleSkin（外置登录）", "enabled": true }
    ]
  },
  "timestamp": 1758100000
}

📎 小提示

id 就是 ?source= 参数可以传的值。

图片接口

GET

头像（方形）

#avatar

/v1/avatar/<name>/<size>

等价写法： GET /v1/avatar/{name}?size={size} —— 尺寸也可以写在查询参数里

玩家头像图，可选方形或圆形裁剪、可选去掉帽子层、可指定背景色。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`size`	number	可选	`128`	边长像素，范围 8–512；写在路径或 `?size=` 里都行
`shape`	string	可选	`square`	形状：`square`（方形）/ `circle`（圆形）
`helm`	number	可选	`1`	传 `0` 去掉帽子 / 头部外层
`bg`	string	可选	`透明`	背景色，格式 `RRGGBB`，例如 `bg=1a1b2e`
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

# 直接保存成文件
curl -o avatar.png "https://api.shizuku.l.cd/v1/avatar/myndlp/128"

# 圆形头像 + 深色背景
curl -o avatar-circle.png "https://api.shizuku.l.cd/v1/avatar/myndlp/256?shape=circle&bg=1a1b2e"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

📎 小提示

直接返回 PNG，不返回 JSON；配合 <img src="..."> 即可使用。

GET

3D 头部

#head

/v1/head/<name>/<size>

带透视的 3D 头部渲染图，可以调整水平与俯仰角度。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`size`	number	可选	`256`	输出边长像素，范围 8–512
`yaw`	number	可选	`0`	水平旋转角度（度），角度参数含义与 3D 渲染图一致
`pitch`	number	可选	`0`	俯仰角度（度），角度参数含义与 3D 渲染图一致
`helm`	number	可选	`1`	传 `0` 去掉帽子 / 头部外层
`bg`	string	可选	`透明`	背景色，格式 `RRGGBB`
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

curl -o head.png "https://api.shizuku.l.cd/v1/head/myndlp/256?yaw=25&pitch=10"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

📎 小提示

适合做列表头像、排行榜标识。

GET

全身立绘

#body

/v1/body/<name>/<size>

正面 / 背面的全身立绘（2D 拼接图），可去掉外层皮肤。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`size`	number	可选	`256`	输出宽度像素，范围 8–512
`view`	string	可选	`front`	视角：`front`（正面）/ `back`（背面）
`outer`	number	可选	`1`	传 `0` 去掉外层（第二层皮肤：帽子 / 外套）
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

curl -o body.png "https://api.shizuku.l.cd/v1/body/myndlp/256?view=front"

# 背面 + 去掉外层
curl -o body-back.png "https://api.shizuku.l.cd/v1/body/myndlp/256?view=back&outer=0"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

GET

3D 渲染图

★ 核心接口 #render

/v1/render/<name>/<size>

由服务端直接渲染的 3D 立体人物图，可自由调整朝向、俯仰、阴影与缩放。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`size`	number	可选	`256`	输出边长像素，范围 8–512
`yaw`	number	可选	`0`	水平旋转角度，范围 -180 ~ 180，`0` 为正面
`pitch`	number	可选	`0`	俯仰角度，范围 -90 ~ 90
`shadow`	number	可选	`1`	是否绘制脚下阴影：`1` 开 / `0` 关
`outer`	number	可选	`1`	是否绘制外层（第二层皮肤）：`1` 开 / `0` 关
`bg`	string	可选	`透明`	背景色，格式 `RRGGBB`
`scale`	number	可选	`服务端默认`	缩放倍率，用于调整人物在画布中的大小
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

# 正面 3D 渲染
curl -o render.png "https://api.shizuku.l.cd/v1/render/myndlp/512"

# 侧身 45°、无阴影、深色背景
curl -o render-side.png "https://api.shizuku.l.cd/v1/render/myndlp/512?yaw=45&pitch=10&shadow=0&bg=1a1b2e"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

📎 小提示

这是本服务的增强能力之一：原版 / 第三方接口只提供 2D 拼接图，这里由服务端实时渲染 3D 立体图。
上传皮肤直接渲染：POST /v1/render/{size}，Content-Type: multipart/form-data，字段 file=@skin.png，可选 model=classic|slim、yaw、pitch，同样返回 PNG，用于「本地皮肤预览」工具。上传上限 2 MB。

GET

等轴测立方体

#cube

/v1/cube/<name>/<size>

等轴测（isometric）风格的方块化头像，适合做图标、徽章。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`size`	number	可选	`256`	输出边长像素，范围 8–512
`yaw`	number	可选	`0`	水平旋转角度（度），角度参数含义与 3D 渲染图一致
`pitch`	number	可选	`0`	俯仰角度（度），角度参数含义与 3D 渲染图一致
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

curl -o cube.png "https://api.shizuku.l.cd/v1/cube/myndlp/256"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

GET

皮肤原图

#skin

/v1/skin/<name>

返回玩家的皮肤原图（未经过任何处理的 PNG），可直接喂给 3D 皮肤查看器。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`download`	number	可选	`0`	传 `1` 时附加下载响应头，浏览器会另存为文件
`upload`	number	可选	`1`	传 `0` 时忽略上传用的皮肤，只回退到正版皮肤
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

curl -o skin.png "https://api.shizuku.l.cd/v1/skin/myndlp"

# 触发浏览器下载
curl -OJ "https://api.shizuku.l.cd/v1/skin/myndlp?download=1"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

📎 小提示

没有皮肤时返回 HTTP 404 + no_texture。

GET

披风原图

#cape

/v1/cape/<name>

返回玩家的披风原图 PNG，参数与皮肤原图一致。

参数

参数名	类型	必填	默认值	说明
`name`	string	必填	`—`	玩家名（也支持 UUID）
`download`	number	可选	`0`	传 `1` 时附加下载响应头
`upload`	number	可选	`1`	传 `0` 时忽略上传用的披风
`source`	string	可选	`auto`	数据源：`auto`（先试 Mojang 正版，再试 LittleSkin）、`mojang`（只查正版）、`littleskin`（只查外置登录账号）

请求示例

bash

curl -o cape.png "https://api.shizuku.l.cd/v1/cape/myndlp"

响应（PNG 二进制）

http

HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, immutable
access-control-allow-origin: *
x-powered-by: NekoSkin-API
content-length: 4312

（响应体是 PNG 二进制数据，用浏览器打开链接即可直接看到图片）

📎 小提示

玩家没有披风时返回 HTTP 404 + no_texture。

账号与 OAuth2

GET

查询正版验证状态

#me-verification

/v1/me/verification

等价写法： GET /v1/me/premium —— 等价写法

查当前登录的 LittleSkin 账号有没有通过「正版验证」。需要授权时的 PremiumVerification.Read 权限。已通过时会给出对应的正版 UUID。

参数

参数名	类型	必填	默认值	说明
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

# 需要先登录（浏览器访问 /oauth/littleskin 完成授权）
curl "https://api.shizuku.l.cd/v1/me/verification?pretty=1" \
     --cookie "nekoskin_sid=<你的会话 Cookie>"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "verified": true,
    "uuid": "69e535e98159409e93c8d649d7355279",
    "checked": true,
    "logged_in": true
  }
}

POST

创建 Minecraft 访问令牌

★ 核心接口 #me-token

/v1/me/token

用当前登录状态为指定角色换一个 Yggdrasil Access Token（给启动器 / 联机工具用）。需要 Yggdrasil.MinecraftToken.Create 权限。⚠️ 令牌等同密码，本站不落盘、不记日志。

参数

参数名	类型	必填	默认值	说明
`uuid`	string	必填	`—`	角色 UUID（可用 /v1/me/profiles 拿到），放在 JSON body 里
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl -X POST "https://api.shizuku.l.cd/v1/me/token?pretty=1" \
     -H "Content-Type: application/json" \
     --cookie "nekoskin_sid=<你的会话 Cookie>" \
     -d '{"uuid":"02231987764f4ef9be364541018d0fa8"}'

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "clientToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "selectedProfile": { "id": "02231987764f4ef9be364541018d0fa8", "name": "myndlp" },
    "availableProfiles": [ { "id": "02231987764f4ef9be364541018d0fa8", "name": "myndlp" } ],
    "created_at": "2026-09-17T14:20:00+08:00",
    "note": "这是直接访问 Yggdrasil API 的凭据，请像密码一样保管，不要泄露给他人"
  }
}

GET

LittleSkin 授权入口

#oauth

/oauth/littleskin

等价写法： GET /oauth/littleskin/callback?code={code} —— 授权回调，登录成功后 302 回 / GET /oauth/logout —— 登出

跳转到 LittleSkin 授权页完成外置登录；登录状态保存在服务端的 Cookie 会话里。

参数

参数名	类型	必填	默认值	说明
`code`	string	必填	`—`	仅回调地址 `/oauth/littleskin/callback` 需要，由 LittleSkin 授权页自动带上，无需手工构造

请求示例

bash

# 查看跳转目标（不跟随重定向）
curl -i "https://api.shizuku.l.cd/oauth/littleskin"

# 登出
curl -i "https://api.shizuku.l.cd/oauth/logout"

响应示例

http

HTTP/2 302
location: <LittleSkin 授权页地址>
cache-control: no-store

（浏览器会自动跳到 LittleSkin 授权页；授权完成后回到
 https://api.shizuku.l.cd/oauth/littleskin/callback?code=... ，
 登录成功再 302 跳回站点首页 /）

📎 小提示

OAuth2 流程需要浏览器携带 Cookie 参与，因此不适合在命令行里直接完成。

GET

当前登录用户

#me

/v1/me

查看当前 Cookie 会话对应的 LittleSkin 登录状态与用户信息。

参数

参数名	类型	必填	默认值	说明
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

# 带上浏览器里的会话 Cookie
curl "https://api.shizuku.l.cd/v1/me?pretty=1" --cookie "PHPSESSID=<你的会话 ID>"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "logged_in": true,
    "user": {
      "id": 1024,
      "name": "myndlp",
      "avatar": "https://littleskin.cn/avatar/1024"
    }
  },
  "timestamp": 1758100000
}

📎 小提示

未登录时不会报错，而是返回 {"logged_in": false}，方便前端直接判断登录态。

GET

当前账号的角色

#me-profiles

/v1/me/profiles

列出当前登录的 LittleSkin 账号拥有的游戏角色，用于让用户挑选要展示的角色。

参数

参数名	类型	必填	默认值	说明
`pretty`	number	可选	`—`	传 `1` 时以缩进美化格式返回 JSON，方便人眼阅读与调试；`0` / `false` 为紧凑输出

请求示例

bash

curl "https://api.shizuku.l.cd/v1/me/profiles?pretty=1" --cookie "PHPSESSID=<你的会话 ID>"

响应示例

json

{
  "code": 0,
  "success": true,
  "message": "ok",
  "data": {
    "profiles": [
      { "id": "d5d2a02a769d4f62b62a19d90e79b2d2", "name": "myndlp" }
    ]
  },
  "timestamp": 1758100000
}

📎 小提示

未登录时同样返回空列表或错误提示，请先访问 /oauth/littleskin 完成授权。

错误码对照表

出错时 success 为 false，code 是稳定的机器可读标识，message 是给人看的中文说明。

code	HTTP	含义
`bad_request`	400	请求参数不合法
`invalid_name`	400	玩家名格式不合法
`invalid_uuid`	400	UUID 格式不合法
`missing_param`	400	缺少必需参数
`too_many_names`	400	批量请求超过上限（最多 100 个）
`bad_source`	400	source 参数非法
`not_found`	404	玩家不存在
`no_texture`	404	该玩家没有皮肤 / 披风
`rate_limited`	429	触发限流，请稍后再试
`upstream_error`	502	上游（Mojang / LittleSkin）故障
`upstream_timeout`	504	上游超时
`render_failed`	500	图像渲染失败
`internal_error`	500	服务端内部错误

json · 404 示例

{
  "code": "not_found",
  "success": false,
  "message": "玩家不存在",
  "data": null,
  "timestamp": 1758100000
}

在线调试器

直接在浏览器里调用本服务的真实接口 —— 纯前端 fetch，同域请求，不需要后端参与，也不需要任何 Key。

选择接口

玩家名 / UUID / 参数

尺寸 size 仅对图片接口生效

数据源 source auto 会自动回退到 LittleSkin

快速试试：

响应 JSON

🔍 关于调试器

请求由你的浏览器直接发出，用的是当前站点的同域地址，不会有跨域问题。
会消耗你自己的限流额度 —— 结果区会显示本次响应里的 X-RateLimit-Remaining，方便观察剩余次数。
需要登录态的接口（/v1/me 等）会带上同域 Cookie；未登录时它们会返回 logged_in: false 而不是报错，这是预期行为。