歌词获取工具 HTTP API 文档

1. 基本信息项目说明 Base URL https://c.cdgz.top 字符编码 UTF-8 服务认证当前未设置 LyricGET API Key 或登录认证跨域访问已启用 CORS 压缩请求包含 Accept-Encoding: gzip 且文本响应不小于 1 KiB 时可能返回 gzip 调用模式同步请求；歌词接口会等待对应平台适配器执行完成所有响应都可能包含以下性能诊断头： Server-Timing: app;dur=12.34 歌词接口的外部平台访问时间受网络、地区限制及平台限流影响。客户端超时时间建议设置为至少 65 秒，与项目网页端保持一致。 2. 接口总览方法路径说明成功响应类型 POST /get-lyrics 根据歌曲或专辑 URL 获取歌词 JSON GET /api/apple 获取 Apple Music 歌词文本文件 UTF-8 纯文本 GET /api/platforms 获取当前支持的平台及适配器目录 JSON POST /convert_text 简繁转换及异体字标准化 JSON 3. 获取歌词 POST /get-lyrics 根据 URL 自动识别音乐平台，执行对应歌词适配器，并返回统一 JSON。请求头 Content-Type: application/json Accept: application/json 请求体字段类型必填说明 url string 是支持平台的歌曲或专辑 URL token string 条件必填平台用户 token；Apple Music 必填，其他平台按需传入 Token 行为：平台要求行为 Apple Music 必填作为 media-user-token 使用；每次都重新请求 Apple API Musixmatch 可选提供 token 时改用 token 适配器 QQ 音乐可选 token 包含喵或 nya 时使用时间轴歌词适配器，否则使用普通歌词适配器其他平台通常不需要未定义特殊逻辑的平台不会使用该字段 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" } 字段类型说明 lyrics string 适配器返回的歌词文本，可能包含 LRC 时间轴、标题或平台特有分隔符 status string 成功时为 success script_warning string 可选；适配器退出成功但向 stderr 输出的提示信息 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 } HTTP 状态码场景 400 请求体为空、URL 为空、token 类型错误、URL 不属于支持平台、Apple token 缺失 403 UtaTime/Uta-Net 类适配器被上游拦截，并可能在响应中提供人工获取说明 404 对应适配器文件不存在 429 目标站点已被服务端临时标记为不可用 500 适配器非零退出、第三方平台请求失败、权限错误或服务内部异常 504 适配器执行超过服务端截止时间通用内部异常可能返回： { "error": "处理请求时出错", "details": "异常详情", "type": "ExceptionType" } 4. Apple Music 文本下载 GET /api/apple 专用于返回可下载的 Apple Music UTF-8 歌词文本。该接口与 /get-lyrics 使用相同的 Apple 适配器，但成功响应不是 JSON。 Query 参数参数类型必填说明 url string 是 Apple Music 歌曲或专辑 URL token string 是用户的 Apple Music media-user-token 参数必须进行 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 无效/过期或链接错误" } HTTP 状态码场景 400 URL/token 缺失，或 URL 不是 Apple Music 链接 401 Apple 适配器报告 403 Forbidden，通常与 token、链接或权限有关 404 内容不存在，或未在 token 对应区域上线 500 Apple 请求、解析或服务内部处理失败 504 Apple 适配器执行超过 38 秒 6. 歌词文字转换 POST /convert_text 执行简繁转换或 CJK 异体字标准化。请求头 Content-Type: application/json 请求体字段类型必填说明 text string 是待转换文本；服务端会移除首尾空白 convert_type string 是转换类型，见下表 convert_type 作用成功响应中的 conversion_type to_simplified 繁体转简体繁体转简体 to_traditional 简体转繁体简体转繁体 normalize_variants CJK 异体字标准化异体字标准化 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": "文本内容为空" } HTTP 状态码场景 400 JSON 请求体为空、文本为空或转换类型无效 500 转换器执行失败 7. 当前支持的平台建议通过 /api/platforms 动态读取支持列表。当前代码包含以下域名：域名平台 awa.fm AWA uta-net.com Uta-Net animesongz.com Animesongz genius.com GENIUS j-lyric.net J-Lyric.net joysound.com JOYSOUND j-total.net J-Total kkbox.com KKBOX music.line.me LINE MUSIC utatime.com UtaTime lyrical-nonsense.com UtaTime musixmatch.com Musixmatch petitlyrics.com PetitLyrics rocklyric.jp ROCK LYRIC linkco.re TuneCore Japan / LinkCore utaten.com Utaten music.163.com、163cn.tv 网易云音乐 y.qq.com QQ 音乐 lyricstranslate.com LyricsTranslate piapro.jp piapro joox.com JOOX music.apple.com Apple Music karent.jp KARENT qishui.douyin.com 汽水音乐