API リファレンス

API のベースパスは /api です。エラー時は JSON を返します。公開環境に配置する場合は、ネットワーク制御や認証をアプリケーションの前段で適切に設けてください。

ヘルスチェック

メソッド	パス	説明
GET	/health	サーバーの稼働状態と時刻を返す

アルバム

メソッド	パス	説明
GET	/albums	アルバム一覧を取得
POST	/albums	{ "name": "..." } で作成
GET	/albums/:id	曲を含む詳細を取得
PUT	/albums/:id	{ "name": "..." } で更新
DELETE	/albums/:id	アルバムを削除
DELETE	/albums/:albumId/tracks/:trackId	アルバムから曲だけを外す

曲と取得

メソッド	パス	説明
GET	/tracks	曲を取得。albumId、page、limit、q を指定可能
POST	/tracks/download	youtubeUrl、任意で albumId と title を送信し取得をキューへ追加
POST	/tracks/upload	multipart/form-data の file、任意で title と albumId を送信
GET	/tracks/:id	曲の詳細を取得
PATCH	/tracks/:id	{ "title": "..." } でタイトルを変更
DELETE	/tracks/:id	曲と関連するメディアを削除
POST	/tracks/bulk-delete	{ "trackIds": ["..."] } で複数削除
POST	/tracks/album	trackId と albumId で曲を追加
DELETE	/tracks/album/:albumId/:trackId	曲をアルバムから外す
POST	/tracks/refresh-metadata	欠損メタデータを再取得

アップロードで受け付ける形式は m4a、mp3、flac、wav、mp4 です。

プレイリストとキュー

メソッド	パス	説明
POST	/playlists/download	playlistUrl と任意の albumName を送信しプレイリスト取得を開始
GET	/queue	キューの状態を取得
GET	/queue/:queueId	キュー項目の詳細を取得
DELETE	/queue/:queueId	キュー項目をキャンセル
DELETE	/queue?clearType=completed	完了・失敗・全件のキュー履歴を削除

clearType には completed、failed、all を指定できます。

ストリーミング

メソッド	パス	説明
GET	/stream/:trackId	Range リクエスト対応のメディアを返す。mode=audio または mode=video を指定可能
GET	/stream/:trackId/metadata	メディアメタデータを取得
POST	/stream/metadata/batch	複数曲のメタデータを一括取得