独立 Node.js 服务:解析 YouTube 音频格式、匹配 YouTube Music 歌曲、创建下载与转码任务。服务地址为 http://127.0.0.1:8787。
所有 /v1/ 请求使用服务端配置的 API_KEY。此页面不读取或保存密钥。
Authorization: Bearer <API_KEY> Content-Type: application/json
成功响应:{"data": ...}。失败响应:{"error":{"code":"...","message":"..."},"requestId":"..."}。文件接口直接返回音频文件。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/tools | 检查下载工具状态 |
| POST | /v1/youtube/resolve | 解析单个 YouTube/YouTube Music 链接 |
| POST | /v1/music/match | 从平台单曲链接或名称资料匹配歌曲 |
| POST | /v1/jobs | 创建下载任务,返回 202 |
| GET | /v1/jobs | 查看保留的任务记录 |
| GET | /v1/jobs/{id} | 查看任务状态和进度 |
| POST | /v1/jobs/{id}/cancel | 取消待处理或运行中的任务 |
| GET / HEAD | /v1/jobs/{id}/file | 获取完成文件,支持 Range,仍需鉴权 |
POST /v1/youtube/resolve
{"url":"https://music.youtube.com/watch?v=EIiC8gIAMgE"}
可选 formatId。响应含标题、艺人、专辑、时长、封面、audioFormats、selectedAudio。可用的音频项提供临时媒体地址、有效期和必要请求头。
媒体地址可能过期或与请求头、服务端出口 IP 有关。需要由本服务下载音频时,请创建任务,再取得任务文件。
POST /v1/music/match
{"url":"https://music.apple.com/cn/song/6781807531"}
或者:
{"title":"写故事的人","artist":"汪苏泷","album":"明日世界ACT I","duration":248.241}
支持可选 isrc,时间单位是秒。直接传名称资料时,专辑和时长至少填写一项。结果为 {metadata,source};source.url 是匹配的歌曲页面。Apple/Spotify/Amazon 用于识别曲目,匹配音频来自 YouTube Music。
POST /v1/jobs
{"url":"https://music.youtube.com/watch?v=EIiC8gIAMgE","format":"mp3"}
GET /v1/jobs/<返回的任务ID>
GET /v1/jobs/<返回的任务ID>/file
格式可选 mp3、m4a、best。任务状态为 queued、resolving、downloading、completed、failed、cancelled 或 expired。完成后 file.downloadPath 为取文件地址。
请求超过速率、等待队列或任务容量上限时会被拒绝。任务结果默认保留 24 小时;到期后 API 不再提供文件访问,磁盘音频需由部署者清理。服务重启后未完成任务会标记取消。
运行 npm run setup 生成配置并检查工具,然后 npm start。默认仅监听本机;对其他设备提供服务时修改 HOST。浏览器跨域调用需配置 CORS_ORIGINS。公网 HTTPS 由反向代理或部署环境提供。
当前 key 为共享访问权限,所有持有者共享任务列表。详细配置、Windows/Linux 路径说明及调用示例见项目 README.md 和 examples/。