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"}'

レスポンスにはジョブ 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 送信先は公開経由で到達可能なホストである必要があります。内部アドレスは拒否されます。
• エクスポートには完了したコード分析が必要です。文字起こしのみのジョブは現時点でエクスポートできません。
• YouTube の Cookie 認証は公開 API からは利用できません。
• 不正防止のためクライアント IP を記録する場合があります。
• ブラウザからのクロスオリジンアクセスは既定で無効です。運営者は PUBLIC_API_CORS_ORIGINS で許可できます。

対話型APIリファレンス

完全なリファレンスを下に読み込みます — すべてのエンドポイントを閲覧し、このページから直接リクエストを試せます。