Music API

プレフィックス: /api/music

音楽の検索、再生、歌詞/メディアプロキシのエンドポイント。これらのルートは完全なインラインパスで宣言され（ルーター自体にはプレフィックスがありません）、すべて /api/music 名前空間に属します。

プロキシ

GET /api/music/proxy

音楽ソースから音声を取得する際に CORS と Referer の制限を回避する汎用メディアプロキシ。音楽ソースのドメインホワイトリストにあるホストのみが許可されます。リダイレクトは追跡されますが、各ホップごとにホワイトリストに対して再検証されます。

クエリ: url — プロキシするリモートメディア URL（http/https である必要があります）。

• キャッシュ/ストリーミングの判定は上流の Content-Length ヘッダーに基づきます（ボディをダウンロードせずヘッダーのみ探測）。
• Content-Length が 10MB 未満のソースはバッファリングされてキャッシュされ（TTL は約 6 時間）、レスポンスには X-Cache: HIT / MISS が付きます。
• 10MB 以上——または Content-Length を省略/秘匿するソースはストリーミングされ（X-Cache: STREAM）、ダウンロードしながら再生を開始できます。
• 50MB のハードサイズ制限が適用されます。

INFO

失敗時、このエンドポイントは適切なステータスコード（例: 400 無効な URL、403 許可されないドメイン、413 サイズ超過、504 タイムアウト）とともに JSON エンベロープ { "success": false, "error": "..." } を返します。

ドメイン

GET /api/music/domains

すべての音楽ソースのドメインリストを返し、フロントエンドが動的ホワイトリストに登録できるようにします（プロキシリクエストの認可に使用されます）。

レスポンス:

{
  "success": true,
  "domains": ["..."]
}

検索

GET /api/music/search

設定された音楽ソース全体を検索するスマート音楽ディスパッチルート。

クエリ:

• query — 検索キーワード（最大長 200）。
• limit — 結果の最大件数（1〜50、デフォルト 10）。フロントエンドがインテリジェントなマッチングを行えるよう、常に最低 5 件の候補が返されます。

レスポンス: 成功時は、マッチしたトラックを含むエンベロープ { "success": true, "data": [...] }。キーワードが空の場合やエラー時は { "success": false, "data": [], "error": "...", "message": "..." }。

再生

GET /api/music/play/netease/{song_id}

NetEase Cloud Music スマートリダイレクトルート。バックエンドの MUSIC_U クッキーを使って実際の高音質 / 認証済み直リンクを解決し、再生のためにそこへリダイレクト（HTTP 307）します。

パスパラメータ: song_id — NetEase の曲 id（10 進数の数字のみ）。

INFO

pyncm_async が利用できない、クッキーが存在しない、または解決に失敗した場合、このエンドポイントは公開の music.163.com 外部 URL へのリダイレクトにフォールバックします。数字でない song_id はステータス 400 で { "success": false, "error": "invalid song_id" } を返します。