做自建音乐网站、网页播放器、小程序音乐组件、音乐机器人的开发者看过来！
这款榜单音乐接口，同时支持网易云（netease）、QQ 音乐（qq）两大平台，传入平台标识 + 榜单 ID，直接返回榜单歌曲列表，自带歌名、歌手、专辑、封面、音频直链、歌词地址、付费标记，拿到数据就可以直接渲染播放器页面。
✅ 接口亮点
- 双平台支持：网易云、QQ 音乐榜单，切换
platform参数即可 - 返回字段齐全：歌名、歌手、专辑、封面、时长、歌曲 ID、音源 src、歌词链接、付费 pay 标识
- 混合鉴权：API Key / APP_ID+APP_SECRET 两种鉴权方式
- 上游透传返回 JSON，结构简单，前端直接渲染
- 错误码体系统一，鉴权、限流、余额、上游异常方便捕获处理
- 自带幂等防重，支持
X-Idempotency-Key避免重复请求
📌 接入基础信息
- 接口路径：
/hqbd - 完整域名：
https://api.xiaotuo.net - 调试入口：
https://api.xiaotuo.net/api/v1/calls/invoke - 请求方式：GET
- 参数位置：Query 参数
- 鉴权：hybrid 混合鉴权
- 响应：auto_upstream，透传上游 JSON
请求参数
表格
| 参数 | 必填 | 说明 | 示例 |
|---|---|---|---|
| platform | 是 | 平台标识，netease= 网易云，qq=QQ 音乐 |
netease |
| topId | 是 | 榜单 ID | 19723756 |
curl 调用示例
curl "https://api.xiaotuo.net/hqbd?platform=netease&topId=19723756"
注意：需要自行追加鉴权凭证，以平台控制台要求为准
成功返回示例
{
"code": 200,
"data": [
{
"album": "蔡镇鸿",
"artist": "谢帝/艾志恒Asen",
"cover": "https://p1.music.126.net/mp2dipDN2BIQ9_MQ-HUfXg==/109951174220484984.jpg",
"duration": 193,
"id": "3457059994",
"lyrics_url": "https://music.xiaotuo.net/api/v1/music/lyric?platform=netease&songId=3457059994",
"pay": false,
"src": "https://m801.music.126.net/.../4fb9525657d7c5edc558df9df767e354.mp3",
"title": "Enjoy the trip"
}
]
}
📋 鉴权说明
混合鉴权二选一：
- API Key 鉴权：缺 Key 返回 100，密钥无效 / 未授权返回 101
- APP_ID + APP_SECRET 鉴权：缺失、不匹配、无效对应 130/131/132/133
额外校验：IP 白名单、黑名单拦截、账号状态校验
🚦 计费与限流
- price=0，计费模式以控制台为准，支持余额、套餐、会员、积分多种模式
- 10005（429）：请求频率超限，读取
Retry-After做退避重试 - 10006（429）：全站免费额度耗尽
- 114（429）：子 API Key 日限额打满
📋 核心错误码速查
表格
| 错误码 | HTTP | 含义 |
|---|---|---|
| 100 | 401 | API Key 为空 |
| 101 | 401 | API Key 无效、未授权 |
| 400 | 400 | 缺少必填参数 |
| 106 | 403 | 余额 / 免费额度不足 |
| 10005 | 429 | 请求频繁限流 |
| 20001 | 502 | 上游服务失败 |
| 20002 | 504 | 上游超时 |
🧩 适用开发场景
- 自建网页音乐播放器、音乐站点
- 小程序、APP 音乐模块
- 音乐机器人、歌单同步工具
- 音乐可视化、榜单展示页面
- 前端 Demo、个人音乐 SaaS 原型
⚠️ 重要提醒
- 接口仅用于学习、开发调试，禁止商用侵权分发音源；
- 上游音源存在失效、防盗链、超时情况，业务层务必做好异常捕获、降级；
- 音源、歌词链接由上游返回，稳定性以上游为准；
- 计费、单价、额度以平台控制台显示为准。
