开发者文档
面向第三方应用 / 网站 / 刷机工具的 ROM 数据接口:全品牌机型目录(含系列分类)、历史版本(含 OTA 更新说明)与官方直链解析,一套 Key 即可接入。
概述
5 大品牌族 · 10 个子品牌
小米 / 红米、OPPO / 一加 / 真我、vivo / iQOO、联想、魅族,统一机型目录与版本模型。
机型目录 + 系列分类
每个机型带
series 系列分类(如 数字系列 / Find / X / 拯救者),可直接做分类筛选。历史版本 + OTA 更新说明
版本带大小 / MD5 / SHA1 / 日期;厂商提供更新说明的写入
changelog,没有则留空。接口为只读查询,服务端对接厂商官方 OTA 接口与社区归档(RomCloud),并统一解析为同一套字段。
Base URL
https://xy.hk2.886966.xyz/rom/v1.php
返回均为 UTF-8 JSON;除 health 外均需携带 API Key。
快速开始
- 获取 API Key前往 申请 API Key(免审核,提交即生成,每人最多 3 把)。
- 确认连通调用一次
health,返回ok: true即接入正常。 - 拉机型目录按品牌组取机型列表,用
series做分类,用has_rom标记暂无 ROM 的机型。 - 查版本 / 拿直链用
versions查历史版本;下载链接若需解析,再调link。
curl "https://xy.hk2.886966.xyz/rom/v1.php?action=health"
curl "https://xy.hk2.886966.xyz/rom/v1.php?action=models&group=xiaomi" \
-H "X-API-Key: xyr_your_key"
鉴权
两种方式任选其一:
- 查询参数:
https://xy.hk2.886966.xyz/rom/v1.php?key=xyr_xxx&action=… - 请求头(推荐):
X-API-Key: xyr_xxx
Key 形如 xyr_ + 32 位十六进制,明文只在生成时显示一次,请妥善保存。服务端只保存 sha256,无法找回。
建议把 Key 放在你自己的服务端转发调用;若写在公开前端里,任何人都能拿你的配额。
接口总览
| action | 鉴权 | 说明 |
|---|---|---|
health | 免鉴权 | 连通性与服务状态 |
brands | API Key | 品牌清单(品牌族 / 子品牌) |
models | API Key | 某品牌组全部机型(含系列分类 series) |
versions | API Key | 某机型全部历史版本(含 OTA 更新说明 changelog) |
link | API Key | 直链解析 / 302 跳转下载 |
全部为 GET(也接受同名 POST 参数)。
health 免鉴权
GET?action=health
接入前的连通性探测,返回服务版本、可用 action 与默认限额。
{
"ok": true, "api": "v1", "version": "1.1.0",
"service": "xy-rom", "time": 1792560000,
"actions": ["brands", "models", "versions", "link", "health"],
"groups": ["xiaomi", "oplus", "vivo", "lenovo", "meizu"],
"limits": { "daily_quota_default": 5000, "concurrency": 3 }
}
brands
GET?action=brands
返回启用中的品牌族与子品牌。group 用于 models,children 是 versions 可用的 brand 取值。
{
"ok": true, "api": "v1", "action": "brands",
"data": { "brands": [
{ "slug": "xiaomi", "name": "小米 / 红米", "group": "xiaomi",
"children": ["xiaomi", "redmi", "poco"] },
{ "slug": "vivo", "name": "vivo / iQOO", "group": "vivo",
"children": ["vivo", "iqoo"] }
// … 共 5 个品牌族
]},
"meta": { "quota": 5000, "used": 1, "remaining": 4999, "reset_at": 1792608000 }
}
models
GET?action=models&group=xiaomi
| 参数 | 必填 | 说明 |
|---|---|---|
group | 是 | xiaomi / oplus / vivo / lenovo / meizu |
机型字段:
| 字段 | 说明 |
|---|---|
key | 机型标识(查版本用;魅族为 phone_id) |
name | 机型名称 |
brand | 子品牌(xiaomi / redmi / oneplus / oppo / realme / vivo / iqoo / lenovo / meizu …) |
series | 系列分类(如 数字系列 / Find 系列 / X 系列;可为空) |
has_rom | 是否已有可下载版本(本地判定,用于排序 / 置灰) |
device_model | 设备型号(vivo / 联想查版本时需要) |
seed_version | 已验证起始版本(联想更新链用,可为空) |
{
"ok": true, "api": "v1", "action": "models",
"data": { "group": "vivo", "count": 2, "models": [
{ "key": "PD2408", "name": "iQOO Neo10", "brand": "iqoo",
"series": "Neo 系列", "has_rom": true,
"device_model": "V2408A", "seed_version": "" }
]},
"meta": { ... }
}
versions
GET?action=versions&brand=oneplus&model=PKG110
返回该机型全部历史版本。brand 必须用子品牌:
| 品牌族 | brand 取值 | 机型参数 |
|---|---|---|
| 小米 / 红米 | xiaomi redmi poco | model=代号(如 umi) |
| OPPO / 一加 / 真我 | oneplus oneplus-global oppo realme | model=产品型号(如 PKG110),可选 region / name |
| vivo / iQOO | vivo iqoo | model=SW 型号 + device_model(如 V2408A),可选 name |
| 联想 | lenovo | device_model(如 TB376FC_PRC) |
| 魅族 | meizu | phone_id(即 models 的 key),可选 name |
版本字段(每条一致):
| 字段 | 说明 |
|---|---|
version | 版本号 |
type | 包类型:recovery(卡刷)/ fastboot(线刷)/ full(全量)/ patch(增量) |
channel | 通道:stable / dev / beta / daily |
region / operator | 地区 / 运营商定制 |
android | 安卓大版本 |
size / md5 / sha1 | 大小(字节)/ 校验值 |
date | 发布日期 |
changelog | OTA 更新说明:文本或链接;厂商没提供就为空——有的就写,没有就算 |
download_url | 下载链接(部分为动态链接,需 link 解析;可为空) |
{
"ok": true, "api": "v1", "action": "versions",
"data": {
"brand": "oneplus", "count": 26,
"source": "danielspringer-catalog",
"versions": [
{ "version": "PKG110_11.C.75_1750_202609240641",
"type": "full", "channel": "stable", "region": "CN",
"android": "16", "size": 6234567890, "md5": "…",
"date": "2026-09-24",
"changelog": "系统:优化部分场景下的系统稳定性…",
"download_url": "https://…/downloadCheck?…" }
]
},
"meta": { ... }
}
link
GET?action=link&url=<下载链接>
| 参数 | 必填 | 说明 |
|---|---|---|
url | 二选一 | 版本里的 download_url;OPlus 动态链接(/downloadCheck?)会自动解析成 CDN 直链 |
key | 二选一 | 魅族下载 key,服务端换取直链 |
redirect | 否 | 加 &redirect=1 直接 302 跳转到直链(适合浏览器 / 下载器) |
仅接受各厂商官方 CDN 域名(白名单见 brands 的域名范围),其余返回 bad_host。小米官方 CDN 直链有 Referer 防盗链,返回里的 proxy 是本站免防盗链代理地址。
{
"ok": true, "api": "v1", "action": "link",
"data": {
"url": "https://bigota.d.miui.com/…/miui_…zip",
"resolved": false,
"proxy": "download.php?type=xiaomi&url=…"
},
"meta": { ... }
}
响应信封
成功
{ "ok": true, "api": "v1", "action": "versions",
"data": { ... },
"meta": { "quota": 5000, "used": 3, "remaining": 4997, "reset_at": 1792608000 } }
失败
{ "ok": false, "error": "今日配额已用完", "code": "quota_exceeded", "api": "v1" }
| 字段 | 说明 |
|---|---|
meta.quota | 该 Key 的每日配额 |
meta.used / remaining | 今日已用 / 剩余次数 |
meta.reset_at | 配额重置时间戳(UTC 零点) |
error / code | 失败时的可读文案 / 机器可读错误码 |
错误码
| code | HTTP | 含义 |
|---|---|---|
missing_action / unknown_action | 400 | 没带 action / action 不存在 |
missing_key / bad_key / invalid_key | 401 | 没带 Key、格式不对、无效或已吊销 |
disabled_key | 403 | Key 被停用 |
quota_exceeded | 429 | 今日配额用完,reset_at 后恢复 |
concurrency_exceeded | 429 | 并发超限,退避重试即可 |
bad_group / missing_brand / bad_brand | 400 | 参数不合法 |
bad_url / bad_host | 400 | url 缺失或主机不在官方 CDN 白名单 |
upstream | 502 | 厂商接口暂时不可用(可指数退避重试) |
internal | 500 | 服务端内部错误 |
调用限额
| 项目 | 规则 |
|---|---|
| 每日配额 | 5000 次 / 天 / Key(UTC 零点重置;实时余量见响应 meta.remaining) |
| 并发上限 | 3 个同时请求;超出返回 429 concurrency_exceeded |
| 结果缓存 | 同参数 30 分钟内命中服务端缓存,不重复请求厂商接口 |
| 申请限制 | 每人最多 3 把 Key;同一 IP 每天最多申请 5 次 |
使用约定
- 数据来自厂商官方接口与社区归档,请勿高频轮询;同参数结果有 30 分钟缓存。
- 直链为厂商 CDN 临时链接,可能随时失效;失效请重新调
versions/link。 - 请勿转售、请勿用于批量爬取;异常流量会被限流或吊销 Key。
- ROM 版权归各厂商所有,本站只做索引与解析。
更新日志
平台自身的更新记录;ROM 包的 OTA 更新说明在 versions 的 changelog 字段(有的就写,没有就算)。
v1.1.0
2026-10-21
开放平台改版:接入 vivo / iQOO、联想品牌组(共 5 大品牌族);models 增加系列分类 series 与 has_rom;
link 支持魅族 key、OPlus 动态链接解析与官方 CDN 白名单;新增用量控制台。
v1.0.0
初始版本
开放 API 上线:brands / models / versions / link / health,
API Key 鉴权 + 每日配额 + 并发限制。
用量控制台
Key 用量查询
输入你的 API Key,查看今日 / 近 7 日调用、action 分布、成功率、配额余量与最近 20 条调用。只能看到当前 Key,不会显示其他开发者数据。