歌词获取工具 HTTP API 文档

1. 基本信息

所有响应都可能包含以下性能诊断头：

Server-Timing: app;dur=12.34

歌词接口的外部平台访问时间受网络、地区限制及平台限流影响。客户端超时时间建议设置为至少 65 秒，与项目网页端保持一致。

2. 接口总览

3. 获取歌词

POST /get-lyrics

根据 URL 自动识别音乐平台，执行对应歌词适配器，并返回统一 JSON。

请求头

Content-Type: application/json
Accept: application/json

请求体

Token 行为：

cURL 示例

普通平台：

curl --request POST "https://c.cdgz.top/get-lyrics" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://genius.com/artist-song-lyrics"}'

网易云音乐单曲（桌面、移动端及短链均可）：

curl --request POST "https://c.cdgz.top/get-lyrics" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://music.163.com/song?id=3420884375"}'

网易云音乐专辑：

curl --request POST "https://c.cdgz.top/get-lyrics" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://music.163.com/album?id=390229202"}'

Apple Music：

curl --request POST "https://c.cdgz.top/get-lyrics" \
  --header "Content-Type: application/json" \
  --data '{
    "url":"https://music.apple.com/us/song/example/123456789",
    "token":"YOUR_MEDIA_USER_TOKEN"
  }'

JavaScript：

const response = await fetch("https://example.com/get-lyrics", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://music.apple.com/us/song/example/123456789",
    token: "YOUR_MEDIA_USER_TOKEN",
  }),
});

const data = await response.json();
if (!response.ok) {
  throw new Error(data.error || `HTTP ${response.status}`);
}
console.log(data.lyrics);

普通成功响应

状态码：200 OK

{
  "lyrics": "[00:01.20]第一行歌词\n[00:05.40]第二行歌词",
  "status": "success"
}

status: success 表示适配器正常退出并形成响应；当第三方平台没有提供歌词时，lyrics 仍可能为空。

带歌曲元数据的成功响应

部分平台会额外返回歌曲信息：

{
  "lyrics": "歌词正文",
  "title": "歌曲名",
  "artist": "歌手名",
  "status": "success"
}

当前支持结构化 title、artist 的适配器包括 AWA、Uta-Net、J-Lyric、JOYSOUND、PetitLyrics、Utaten、Animesongz、TuneCore 和网易云音乐。

网易云音乐行为

• 支持 music.163.com 的单曲、专辑、移动端及 #/song、#/album 链接，也支持 163cn.tv 等网易云短链解析。
• 单曲请求调用本机网易云 API 的 /lyric/new?id=... 和 /song/detail?ids=...，分别取得歌词与歌曲名/艺人名。
• 专辑请求只调用一次 /album?id=... 取得曲序及歌曲名/艺人名，再并发调用各曲目的 /lyric/new?id=...；不会为专辑曲目调用 /song/detail。
• 返回的网易云歌词已移除 LRC 时间轴、作词/作曲等创作者信息；时间戳表示的空行仍保留为空白行。
• 本机网易云 API 基地址默认为 http://127.0.0.1:3000。部署时可用 LYRICGET_NETEASE_API_BASE_URL 覆盖。

专辑/多曲目响应

当网易云专辑或 LinkCore/TuneCore 链接解析出多首歌曲时，返回：

{
  "status": "success",
  "album_links": [
    "https://music.163.com/song?id=3420884375"
  ],
  "all_lyrics": [
    {
      "url": "https://music.163.com/song?id=3420884375",
      "lyrics": "歌词正文",
      "title": "歌曲名",
      "artist": "歌手名"
    }
  ]
}

单曲处理失败时，对应数组元素可能改为：

{
  "url": "https://music.163.com/song?id=3420884375",
  "title": "歌曲名",
  "artist": "歌手名",
  "error": "未找到歌词"
}

缓存响应头

X-LyricGET-Cache: HIT

或：

X-LyricGET-Cache: MISS

• 非 Apple 平台只缓存包含歌词的成功结果。
• 默认缓存时间为 5 分钟，缓存键由 URL 和 token 的 SHA-256 哈希构成。
• 错误、超时和空歌词不缓存。
• Apple Music 完全绕过歌词结果缓存，始终返回 MISS。
• Apple Music 响应同时包含：

Cache-Control: no-store, private, max-age=0
Pragma: no-cache
Expires: 0

错误响应

基础错误结构：

{
  "error": "错误说明"
}

适配器执行失败时可能包含诊断字段：

{
  "error": "请求被暂时拦截，请稍后再试",
  "script_error": "上游错误信息",
  "return_code": 1
}

通用内部异常可能返回：

{
  "error": "处理请求时出错",
  "details": "异常详情",
  "type": "ExceptionType"
}

4. Apple Music 文本下载

GET /api/apple

专用于返回可下载的 Apple Music UTF-8 歌词文本。该接口与 /get-lyrics 使用相同的 Apple 适配器，但成功响应不是 JSON。

Query 参数

参数必须进行 URL 编码。

cURL 示例

curl --get "https://c.cdgz.top/api/apple" \
  --data-urlencode "url=https://music.apple.com/us/song/example/123456789" \
  --data-urlencode "token=YOUR_MEDIA_USER_TOKEN" \
  --output lyrics.txt

成功响应

状态码：200 OK

Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="example.txt"
X-LyricGET-Cache: MISS
Cache-Control: no-store, private, max-age=0
Pragma: no-cache
Expires: 0

响应体为歌词纯文本：

歌曲标题
[00:01.20]第一行歌词
[00:05.40]第二行歌词

文件名取自 Apple Music URL 中的歌曲或专辑 slug，并清理不安全字符；无法提取时使用 apple_music_lyrics.txt。

错误响应

错误仍以 JSON 返回：

{
  "error": "Token 无效/过期或链接错误"
}

6. 歌词文字转换

POST /convert_text

执行简繁转换或 CJK 异体字标准化。

请求头

Content-Type: application/json

请求体

cURL 示例

curl --request POST "https://c.cdgz.top/convert_text" \
  --header "Content-Type: application/json" \
  --data '{"text":"漢字歌詞","convert_type":"to_simplified"}'

成功响应

状态码：200 OK

{
  "success": true,
  "converted_text": "汉字歌词",
  "original_length": 4,
  "converted_length": 4,
  "conversion_type": "繁体转简体"
}

错误响应

{
  "success": false,
  "error": "文本内容为空"
}

7. 当前支持的平台

建议通过 /api/platforms 动态读取支持列表。当前代码包含以下域名：