开放平台 v2.3.0 已发布 — 新增实时歌词 WebSocket 接口

汽水音乐
开发者平台

为开发者提供稳定、高效的汽水音乐开放接口。通过 REST API 与 WebSocket 实时通道,将海量正版音乐数据、智能推荐算法和用户授权体系集成到你的应用中。

$ curl -X GET "https://api.qishuiyinyue.dev/v2/search" \
> -H "Authorization: Bearer qs_token_xxx" \
> -d "keyword=晴天&type=track&limit=10"
// Response 200 OK
{ "code": 0, "data": { "tracks": [...], "total": 142 }, "request_id": "qs_req_a1b2c3" }
99.97%
API 可用性 SLA
< 80ms
平均响应延迟
50+
开放 API 端点
8 种
编程语言 SDK

核心接口概览

所有接口遵循 RESTful 设计规范,使用 JSON 格式交换数据,支持 OAuth 2.0 授权码流程和 API Key 两种认证方式。

GET
/v2/search

全站搜索接口,支持按歌曲名、歌手、专辑、歌词关键词进行综合搜索。返回结构化歌曲信息包括封面、时长、播放地址等。

GET
/v2/tracks/{track_id}

获取单首歌曲的完整元数据,包括高音质播放链接、歌词(逐行动态歌词 + 静态文本)、关联歌单、相似歌曲推荐。

GET
/v2/playlists/{playlist_id}

获取歌单详情及歌曲列表,支持分页加载。返回歌单创建者信息、播放量、收藏数、标签分类等社交属性数据。

GET
/v2/artists/{artist_id}

获取歌手/艺术家资料页数据,包括热门歌曲TOP50、专辑列表、相似歌手推荐、艺人简介及高清头像资源。

POST
/v2/recommend/feed

基于用户画像和听歌历史的个性化推荐Feed流。返回混合内容:单曲、歌单、专辑及推荐理由,支持无限下拉加载。

GET
/v2/charts/{chart_type}

获取各类排行榜数据:热歌榜、新歌榜、飙升榜、原创榜。支持按地区和语种筛选,每小时更新一次排名数据。

POST
/v2/user/history

上报用户听歌行为数据(需用户授权),用于构建个人听歌画像。支持批量上报,单次最多提交100条听歌记录。

GET
/ws/v2/lyrics

WebSocket 实时歌词通道。订阅歌曲播放进度后,服务端按时间轴推送当前歌词行,延迟低于50ms,用于实现逐行高亮效果。

多语言 SDK

官方维护的客户端 SDK,覆盖主流编程语言,开箱即用,持续更新。

版本变更记录

关注 API 和 SDK 的最新变化,确保你的应用始终运行在最佳状态。

2024-12-20
v2.3.0

新增实时歌词 WebSocket 通道

新增 /ws/v2/lyrics 端点,支持按时间轴推送滚动歌词。同步优化了搜索接口的响应速度,平均延迟降低 22%。修复了歌单接口在大数据量场景下的分页偏移 Bug。

2024-11-08
v2.2.0

Java SDK 升级 + 推荐接口增强

Java SDK 升级至 v2.2.0,支持响应式编程模型(Reactor/RxJava)。推荐 Feed 接口新增场景标签参数,可按运动、学习、通勤等场景返回定制化推荐结果。

2024-10-15
v2.1.0

Go SDK 发布 + Webhook 事件通知

发布 Go 语言 SDK v2.1.0。新增 Webhook 回调机制,开发者可订阅用户授权变更、歌曲状态更新等事件。API 文档新增交互式调试控制台。

2024-09-01
v2.0.0

API v2 正式发布

全面升级至 v2 架构,采用 JSON:API 规范,统一错误码体系,新增请求链路追踪(x-request-id)。废弃 v1 部分旧接口,提供一键迁移工具。

开发者 FAQ

接入汽水音乐开放平台时的常见问题与解答。

如何申请汽水音乐 API 的开发者密钥?

访问汽水音乐开发者平台(developer.qishuiyinyue.dev),使用汽水音乐账号或抖音账号登录后,在控制台创建应用即可获得 App ID 和 App Secret。个人开发者每天可免费调用 10000 次 API,企业认证后可提升至每天 100 万次。

API 的认证方式有哪些?

汽水音乐开放平台支持两种认证方式:1) OAuth 2.0 授权码模式——适用于需要访问用户私有数据(如听歌历史、收藏歌单)的场景,需要用户显式授权;2) API Key 模式——适用于仅需公开数据(搜索、排行榜、歌曲元数据)的场景,在请求头中携带 X-API-Key 即可。

SDK 是否支持异步/非阻塞调用?

是的。所有官方 SDK 均支持异步调用模式:Node.js SDK 基于 Promise/async-await,Python SDK 支持 asyncio,Java SDK v2.2+ 支持 Reactor 响应式编程,Go SDK 原生支持 goroutine 并发。你可以在 SDK 文档的「异步调用」章节查看各语言的详细用法。

API 的速率限制是多少?如何处理超限?

基础速率限制为每秒钟 50 次请求(QPS),企业认证用户可提升至 500 QPS。当触发限流时,API 会返回 HTTP 429 状态码,响应头中的 X-RateLimit-Reset 字段指示了限流重置时间(Unix 时间戳)。建议在客户端实现指数退避重试策略(如首次等待 1 秒,第二次等待 2 秒,以此类推)。

搜索接口返回的播放链接有效期是多久?

出于版权保护和防盗链考虑,API 返回的歌曲播放 URL 有效期为 30 分钟。过期后需重新调用接口获取新链接。如果你需要长时间缓存播放地址,建议在链接失效前自动刷新。WebSocket 实时歌词通道不受此限制,连接建立后可维持至歌曲播放结束。

v1 旧版 API 还能继续使用吗?

v1 API 已进入维护模式,不再添加新功能,但现有接口仍可正常使用。我们建议所有开发者迁移至 v2 版本以获得更好的性能和更多功能。平台提供了详细的迁移指南和命令行迁移工具(qs-migrate),可以在控制台的「API 升级」页面下载使用。

开始构建你的音乐应用

接入汽水音乐开放平台,获取海量正版音乐数据和智能推荐能力。

📖 阅读开发文档 🔑 获取 API Key