Magic Chords 公开 API

一个版本化的 REST API，用于和弦识别、歌词转录与乐谱导出。所有端点位于 /api/v1/ 之下，接受并返回 JSON（上传与生成的文件除外），在公平配额内向匿名开发者开放。

每个端点都在下方嵌入的参考文档中以交互方式呈现，该文档直接由实现生成并始终保持最新。

工作方式

分析与转录异步执行：提交任务后获得 job_id，轮询状态，处理完成后获取完整结果。

快速开始

为歌曲 URL 提交和弦分析：

curl -X POST https://magic-chords.dev/api/v1/analyze/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

响应包含你的任务句柄：

{"job_id": "bBm3Zx8kQ7...", "status": "processing"}

轮询直到状态变为 complete：

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7...

获取和弦、速度、调性与结构：

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../result

或直接下载导出文件（pdf、midi、musicxml、txt、csv、json）：

curl -o chords.pdf \
  "https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../export?format=pdf"

若要分析本地音频文件而非 URL：

curl -X POST https://magic-chords.dev/api/v1/analyze \
  -F "file=@song.mp3"

端点

速率限制

匿名客户端按 IP 地址限流。当前默认值（也可通过 /api/v1/limits 实时查询）：

每个计量的响应都带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。达到限制时会收到带 Retry-After 头的 429 响应——请遵循它。

错误

注意事项

• 请将 job_id 视为能力令牌：任何持有者都能读取该任务的结果。
• URL 提交必须指向公网可达的主机；内部地址会被拒绝。
• 导出需要已完成的和弦分析；仅转录的任务暂不能导出。
• 公开 API 不支持 YouTube Cookie 认证。
• 可能会记录客户端 IP 以防止滥用。
• 浏览器跨域访问默认关闭；运营者可通过 PUBLIC_API_CORS_ORIGINS 放行来源。

交互式 API 参考

完整参考文档将在下方加载 — 浏览所有端点并直接在本页试用请求。