HTTP JSON API · VERSION 1.0.0

YouTube API

独立 Node.js 服务:解析 YouTube 音频格式、匹配 YouTube Music 歌曲、创建下载与转码任务。服务地址为 http://127.0.0.1:8787。

下载 OpenAPI 描述 · 查看健康状态

鉴权与响应

所有 /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 为取文件地址。

每分钟默认可查询单个任务的进度共 900 次、创建任务 10 次、读取文件 20 次。其他业务接口共用每分钟 60 次,每组独立计数。各任务 ID 共用进度查询额度,HEAD 与每次 Range 均占用一次文件读取额度。响应头 X-RateLimit-Limit 给出本组额度。

任务结果默认保留 24 小时;到期后 API 不再提供文件访问,磁盘音频需由部署者清理。服务重启后未完成任务会标记取消。

配置与部署

运行 npm run setup 生成配置并检查工具,然后 npm start。默认仅监听本机;对其他设备提供服务时修改 HOST。浏览器跨域调用需配置 CORS_ORIGINS。公网 HTTPS 由反向代理或部署环境提供。

当前 key 为共享访问权限,所有持有者共享任务列表。详细配置、Windows/Linux 路径说明及调用示例见项目 README.md 和 examples/。