版本 v1.1 · 更新于 2026-10-18 · 适用于 yy.zddyr.top 认证服务与音乐解析 API
本文档覆盖第三方接入的全部内容：认证方式、限速规则、接口列表、错误码与最佳实践。阅读顺序建议：快速开始 → 认证 → 限速 → 按需查接口。
开发者可用的凭证共两种：API 密钥（音乐解析）与 OAuth 2.0 应用（收藏等敏感数据，需申请审核）。
client_id / client_secret。# 音乐解析（API 密钥，GET）
curl "https://yy.zddyr.top/lx/api/?types=search&source=kw&name=海阔天空&key=你的密钥"
# 开放接口（API 密钥，POST）
curl https://yy.zddyr.top/auth/api.php \
-H "Authorization: Bearer xhkey_your_key_here" \
-d "action=me"返回示例：
{
"code": 200,
"msg": "ok",
"data": { "user": { "id": 12, "username": "demo", "email": "demo@example.com" } }
}POST https://yy.zddyr.top/auth/api.php，参数放 JSON body 或表单，action 指定操作；音乐解析 API 为 GET，见下文。面向开发者的凭证只有两种，按访问的数据类型选择：
| 凭证 | 能访问什么 | 获取方式 | 状态 |
|---|---|---|---|
| ① API 密钥 | 音乐解析 API（搜索 / 播放地址 / 歌词等） | 开发者平台「API 密钥」卡提交申请 → 通过后领取（个人认证免审，其余管理员审核） | 推荐 |
| ② OAuth 2.0 应用 | 收藏、番茄下载记录等敏感个人信息；授权登录（user:read） |
开发者平台提交申请 → 管理员审核通过后发放 | 需申请 |
密钥由服务端生成（xhkey_ 开头），与账号密码解耦：泄露了只删这一个密钥，不影响账号。已改为申请制：在开发者平台「API 密钥」卡提交申请（填备注名与用途说明），个人认证（个人类开发者）用户提交即过，其余经管理员审核；通过后点「领取密钥」获取完整密钥，请求头二选一：
Authorization: Bearer <密钥>
# 或
X-Api-Key: <密钥>?key=（GET 场景图方便，服务端日志已脱敏）。收藏、番茄下载记录属于敏感个人信息，不开放自助直开：先在开发者平台提交应用申请，管理员审核通过后才创建应用并发放 client_id / client_secret。第三方应用凭这对凭证，经用户本人授权后访问其数据。
client_secret——仅显示这一次，请当场保存。client_secret（服务端只存哈希）。泄露或怀疑泄露时再重置一次，旧密钥立即失效。# 1. 跳转用户到授权页（用户在浏览器完成登录与同意；PKCE 的 S256 challenge 必填）
GET https://yy.zddyr.top/auth/oauth.php?action=authorize
?client_id=你的client_id
&redirect_uri=https://your.app/callback
&response_type=code
&scope=favorites:read%20favorites:write
&state=随机串
&code_challenge=BASE64URL(SHA256(code_verifier))
&code_challenge_method=S256
# 2. 回调得到 code，换取访问令牌
POST https://yy.zddyr.top/auth/oauth.php
{"action":"token","code":"授权码","client_id":"...","client_secret":"...","code_verifier":"第1步的原文"}
# 3. 携带访问令牌调用接口
Authorization: Bearer <access_token>
# 4. 校验 / 注销令牌
{"action":"introspect","token":"..."}
{"action":"revoke","token":"..."}favorites:read（读收藏）、favorites:write（写收藏）、fanqie_downloads:read（番茄下载记录）、user:read（授权登录·读取基本信息）。想让你的应用提供「使用星海账号登录 / 注册」？申请应用时勾选 user:read 权限，走与上面完全相同的授权码 + PKCE 流程拿到 access_token，然后调用用户信息端点识别用户：
# 用 access_token 换取用户基本信息（令牌需含 user:read scope）
GET https://yy.zddyr.top/auth/oauth.php?action=userinfo
Authorization: Bearer <access_token>
# 返回示例
{
"sub": 123, // 稳定账号 ID——请以此为用户唯一键
"id": 123,
"username": "zhangsan",
"email": "zhangsan@example.com",
"email_verified": true,
"avatar": "https://..."
}sub 是该用户在你应用下的稳定标识，登录取到后直接建立本地账号关联即可。email_verified 为 true 表示邮箱已验证，可放心用于注册填充。普通用户与开发者都只按「单 IP 每秒」限速（默认 3 次/秒）。开发者等级只是把这个数值按比例放大，不改变计费维度。NAT/代理后面的多个用户共享同一个 IP 的额度——把服务端调用也收敛到固定出口 IP，避免互相挤占。
| 等级 | 每秒放大 | 单日封顶 | 获取方式 |
|---|---|---|---|
| 普通用户 | 基准 | 10000 次 | 注册即得 |
| 普通 | +10% | 默认封顶 | 个人类申请，免网站验证，提交即通过 |
| L1 | +30% | 默认封顶 | 人工审核（L4 封顶；网站类需先网站验证） |
| L2 | +40% | 默认封顶 | |
| L3 | +50% | 默认封顶 | |
| L4 | +100% | 无限 | |
| L4 以上 | 自定义 | 自定义 | 联系管理员单独定制 |
max(基础+1, round(基础 × (1+boost%)))。例：基础 3 次/秒 + 40% → 4 次/秒；基础 10000/日 + 200% → 30000/日。L4 的「无限」只取消单日封顶，每秒限流依然生效。| 层 | 维度 | 默认值 |
|---|---|---|
| OAuth 应用级 | client_id / 分钟 | 120 次（管理员可调） |
| 音乐 API 平台级 | 平台 / 秒（所有 IP 共享） | 管理面板可调 |
| 音乐 API 单 IP | IP / 窗口 | 管理面板可调（1~8 次/1~3 秒） |
| 音乐 API 每小时 | IP / 小时 | 管理面板可调（0=不限） |
超限返回 HTTP 429，body 形如：
{
"code": 429,
"msg": "请求过于频繁：后端密钥默认每秒 3 次，请 1 秒后重试",
"data": { "retry_after": 1, "limit": 3, "scope": "second" }
}同时响应头带：
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1760000000
Retry-After: 1客户端应尊重 Retry-After 退避后重试，不要立即重连——那只会延长封禁观感。
统一入口 POST https://yy.zddyr.top/auth/api.php，action 参数区分操作；认证方式任选其一（API 密钥 / OAuth access_token）。
| action | 说明 | 主要参数 |
|---|---|---|
| me | 当前凭证对应的账号信息 | — |
| fav_list | 云端收藏列表 | page, limit |
| fav_add | 新增收藏 | song 对象 |
| fav_remove | 移除收藏 | id 或 song_id |
| fav_toggle | 有则删、无则加 | song 对象 |
| fav_sync | 批量同步（本地→云端） | songs 数组 |
| fav_oldest | 最早收藏的 N 首（清理用） | n |
| fanqie_downloads | 番茄小说下载记录列表 | page, limit |
| fanqie_download_get | 单条下载记录详情 | id |
fav_* / fanqie_downloads* 属于敏感数据：用 OAuth access_token（对应 scope）调用，代表已授权的终端用户；也可用 API 密钥 调用，访问的是密钥所属账号自己的数据。| action | 说明 |
|---|---|
| ticket_create | 提交工单 |
| ticket_list | 我的工单列表 |
| ticket_detail | 工单详情（含回复） |
| ticket_reply | 回复工单 |
| ticket_close | 关闭工单 |
| action | 说明 |
|---|---|
| oauth_my | 我已授权的第三方应用列表 |
| oauth_revoke | 取消对某个应用的授权（令牌立即失效） |
OAuth 提供侧接口（authorize / token / introspect / revoke / userinfo）走 https://yy.zddyr.top/auth/oauth.php；应用需先在开发者平台提交申请、审核通过后获得。
独立服务，GET 调用：
# 搜索
GET https://yy.zddyr.top/lx/api/?types=search&source=kw&name=海阔天空&key=你的密钥
# 获取播放地址
GET https://yy.zddyr.top/lx/api/?types=url&source=kw&id=12345&key=你的密钥key（API 密钥）走授权档，限速更高；否则未授权档。source 可选 kg / kw / qq / mg / mg2 / nt / qi / kuwo 等，以面板显示为准。| HTTP | code | 含义 | 处理建议 |
|---|---|---|---|
| 200 | 200 | 成功 | — |
| 400 | 400 | 参数错误 / 业务校验失败 | 检查 msg 字段，修正参数 |
| 401 | 401 | 未登录 / 凭证无效或已过期 | 重新获取凭证；密钥被停用则换一把 |
| 403 | 403 | 无权限（scope 不足 / 功能未开启） | 检查开关与授权 scope |
| 404 | 404 | 接口或资源不存在 | 核对 action 拼写 |
| 429 | 429 | 触发限流 | 按 Retry-After 退避重试 |
| 500 | 500 | 服务端内部错误 | 稍后重试；持续失败请用工单反馈 |
code != 200 的形式，一律以 body 的 code 字段为准。?key= 是唯一例外。fav_sync 一次同步，不要循环单条 add。state 必须带并校验，防 CSRF；PKCE 的 code_verifier 妥善保存，换令牌要用。ticket_create 或站内工单反馈，附上请求时间与 action。