音乐 API 文档

酷我音乐搜索、歌词与播放接口，无需鉴权、无 KV 存储依赖。

BASE_URL

接口目录

GET /api/lyrics

获取酷我音乐歌词。同时返回普通歌词 lyrics 与逐字歌词 enhanced（卡拉OK格式）。结果缓存 1 小时。

请求参数

参数类型说明
id必填 string 歌曲 RID（来自搜索接口）

请求示例

curl ""

成功响应

{
  "ok": true,
  "lyrics": "[00:00.000]夜曲 - 周杰伦\n[00:05.120]...",
  "enhanced": "[00:05.120]一群嗜血的蚂蚁[00:06.500]被腐肉所吸引...",
  "source": "kuwo"
}

字段说明

字段类型说明
lyricsstring普通 LRC 歌词，逐行时间戳
enhancedstring逐字歌词（卡拉OK 格式），每行内含 [mm:ss.xxx] 逐字时间戳；无逐字歌词时为空字符串
▶ 在线测试
GET /api/play

根据歌曲 RID 获取播放直链，返回 JSON 格式。不再使用 302 重定向，字段包含 playurl / url / format。优先使用酷我官方 mobi 接口获取 FLAC 无损，失败时自动切换多个备用源。

请求参数

参数类型说明
id必填 string 歌曲 RID（来自搜索接口）

请求示例

curl ""

成功响应

{
  "ok": true,
  "playurl": "https://xxx.com/xxx.flac",
  "url": "https://xxx.com/xxx.flac",
  "format": "flac"
}

失败响应

{
  "error": "未找到可用源"
}
// HTTP 404

字段说明

字段类型说明
playurlstring音频直链（与 url 相同，便于直观使用）
urlstring音频直链（兼容旧字段名）
formatstring音频格式：flac 或 mp3

前端播放示例

// 获取播放直链并交给 <audio> 播放
const res = await fetch(`BASE_URL/api/play?id=${rid}`);
const data = await res.json();
if (data.ok) {
  const audio = document.querySelector('audio');
  audio.src = data.playurl;
  audio.play();
}
▶ 在线测试

🐍 Python 调用示例

下面示例演示通过 /api/play 获取音乐下载直链。修改自用户提供的旧版代码，已适配新版 JSON 返回格式。

安装依赖

pip install requests

完整代码

import requests

music_id = input("请输入音乐 ID: ")
url = f"BASE_URL/api/play?id={music_id}"
headers = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

resp = requests.get(url, headers=headers, timeout=15)
data = resp.json()

if data.get("ok"):
    playurl = data.get("playurl") or data.get("url")
    audio_format = data.get("format", "mp3")
    print("音乐下载直链：", playurl)
    print("音频格式：", audio_format)

    # 可选：直接下载到本地
    # audio = requests.get(playurl, headers=headers, timeout=30)
    # with open(f"{music_id}.{audio_format}", "wb") as f:
    #     f.write(audio.content)
    # print("已保存到本地")
else:
    print("获取失败：", data.get("error", "未知错误"))

运行效果

$ python play.py
请输入音乐 ID: 76331783
音乐下载直链： https://xxx.com/xxx.flac
音频格式： flac

代码说明

变化点说明
解析 JSON 新版 /api/play 返回 JSON，需要用 resp.json() 解析，不再直接读取 resp.url
获取直链 从 data["playurl"]（或 data["url"]）字段取音频直链
超时保护 增加 timeout=15，避免请求挂起
错误处理 判断 data["ok"] 再取直链，避免无源时崩溃
可选下载 注释里提供了直接下载到本地文件的示例代码