开发者文档

面向第三方应用 / 网站 / 刷机工具的 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。

快速开始

  1. 获取 API Key前往 申请 API Key(免审核,提交即生成,每人最多 3 把)。
  2. 确认连通调用一次 health,返回 ok: true 即接入正常。
  3. 拉机型目录按品牌组取机型列表,用 series 做分类,用 has_rom 标记暂无 ROM 的机型。
  4. 查版本 / 拿直链用 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免鉴权连通性与服务状态
brandsAPI Key品牌清单(品牌族 / 子品牌)
modelsAPI Key某品牌组全部机型(含系列分类 series)
versionsAPI Key某机型全部历史版本(含 OTA 更新说明 changelog)
linkAPI 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 pocomodel=代号(如 umi)
OPPO / 一加 / 真我oneplus oneplus-global oppo realmemodel=产品型号(如 PKG110),可选 region / name
vivo / iQOOvivo iqoomodel=SW 型号 + device_model(如 V2408A),可选 name
联想lenovodevice_model(如 TB376FC_PRC)
魅族meizuphone_id(即 models 的 key),可选 name

版本字段(每条一致):

字段说明
version版本号
type包类型:recovery(卡刷)/ fastboot(线刷)/ full(全量)/ patch(增量)
channel通道:stable / dev / beta / daily
region / operator地区 / 运营商定制
android安卓大版本
size / md5 / sha1大小(字节)/ 校验值
date发布日期
changelogOTA 更新说明:文本或链接;厂商没提供就为空——有的就写,没有就算
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": { ... }
}

响应信封

成功
{ "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失败时的可读文案 / 机器可读错误码

错误码

codeHTTP含义
missing_action / unknown_action400没带 action / action 不存在
missing_key / bad_key / invalid_key401没带 Key、格式不对、无效或已吊销
disabled_key403Key 被停用
quota_exceeded429今日配额用完,reset_at 后恢复
concurrency_exceeded429并发超限,退避重试即可
bad_group / missing_brand / bad_brand400参数不合法
bad_url / bad_host400url 缺失或主机不在官方 CDN 白名单
upstream502厂商接口暂时不可用(可指数退避重试)
internal500服务端内部错误

调用限额

项目规则
每日配额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,不会显示其他开发者数据。

还没有 Key?申请一把