Free2 下載 API
介面說明
Free2 是獨立的付費下載通道：按歌曲 ID（或 suno.com 歌曲連結）解析出 MP3/WAV/歌詞/中繼資料 檔案，返回平台託管的下載位址。它只接受 API Key，不接受瀏覽器登入態，返回值裡也不包含 Suno 的加密播放源。
介面位址：POST /api/music/free2
計費：按成功首數計費，目前預設 0.2 元/首。一次請求裡選幾個檔案類型都不額外加價； 解析失敗的首數不收費。單次最多 10 首（去重後），實際扣費以後台價格設定為準。
推薦模型：suno-v6。可用 suno-v6、suno-v6-wild 或 suno-v6-mini。
驗證
| 參數名 | 型別 | 必填 | 說明 |
|---|---|---|---|
| Authorization | string | 是 | Bearer YOUR_API_KEY |
| Content-Type | string | 是 | application/json |
請求參數
| 參數名 | 型別 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
| song_id | string | 否 | - | 單首歌 ID，也可以是 suno.com 歌曲連結（含 /s/ 短鏈） |
| song_ids | string[] | 否 | - | 多首寫法（推薦），單次最多 10 首 |
| songs | string[] | 否 | - | song_ids 的別名 |
| files | string[] | 是 | - | 需要的檔案類型，可選 mp3、wav、lyrics、metadata；m4a 不支援 |
song_id 與 song_ids 至少提供一個；files 至少一個。
請求範例
curl -X POST https://www.suno-api.io/api/music/free2 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"song_ids": ["song_id_1", "song_id_2"],
"files": ["mp3", "wav", "lyrics"]
}'
回應結果
{
"code": 200,
"message": "success",
"data": {
"songs": [
{
"song_id": "song_id_1",
"files": [
{"type": "mp3", "url": "https://media.suno-api.io/assets/song_id_1-free2-v1-mp3.mp3"}
]
},
{
"song_id": "song_id_2",
"files": [],
"error": {"code": "song_not_found", "message": "song not found or not owned by the current user"}
}
],
"requested_songs": 2,
"succeeded_songs": 1,
"price": 0.2
}
}
| 欄位 | 型別 | 說明 |
|---|---|---|
| songs | array | 每首歌的處理結果：song_id、files[]、失敗時帶 error |
| requested_songs | number | 正規化去重後的歌曲數 |
| succeeded_songs | number | 成功數量，計費按這個數字 |
| price | number | 本次實際扣費（元） |
只請求一首歌時，回應裡還會額外返回頂層 song_id 與 files，相容舊版單首寫法。
复用快取位址（不計費）
已經下載過的歌，再次下載不必重新解析、也不再扣費：用 POST /api/music/free2/cached
取回該帳號先前下載過的那批檔案的當前位址。
介面位址：POST /api/music/free2/cached
計費：免費。唯讀快取，不解析、不轉碼、不扣費；只返回已經準備好且未被回收的位址。
⚠️ 下載位址有效期：7 天，請及時轉存。
songs[].files[].url由平台物件儲存提供，預設 7 天後失效（檔案到期回收，舊位址返回 404）；請在這 7 天內轉存到你自己的儲存。位址過期後，重新呼叫POST /api/music/free2重新準備即可拿到新的有效位址（該次重新準備按正常計費規則收費；/api/music/free2/cached只返回仍然有效的快取位址）。
請求參數：與 POST /api/music/free2 完全相同（song_id / song_ids / songs 任一，files 至少一個）。
curl -X POST https://www.suno-api.io/api/music/free2/cached \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "song_ids": ["98ca3f1d-…", "a185b3d9-…"], "files": ["mp3"] }'
{
"success": true,
"data": {
"items": [
{ "song_id": "98ca3f1d-…", "type": "mp3", "url": "https://…/assets/98ca3f1d-…-free2-v1-mp3.mp3" }
],
"songs": [
{ "song_id": "98ca3f1d-…", "files": [ { "type": "mp3", "url": "https://…" } ], "missing_files": [] },
{ "song_id": "a185b3d9-…", "files": [], "missing_files": ["mp3"] }
],
"missing": ["a185b3d9-…"]
}
}
| 欄位 | 型別 | 說明 |
|---|---|---|
| items | array | 可直接下載的位址清單（song_id + type + url） |
| songs | array | 按歌曲分組的結果，missing_files 是這次沒命中快取的格式 |
| missing | string[] | 這首歌一個可用快取都沒有（需要改用 POST /api/music/free2 重新解析，那一步按首計費） |
只有你此前下載過的歌曲才會返回位址；沒有下載記錄、或資產已被回收的歌曲一律只出現在
missing 裡，不會返回任何位址。
注意事項
POST /api/music/free2可以解析 Suno 上任意公開歌曲（含不在本平台的歌），歌曲無法解析時會在該首上返回error，不影響同批次其它歌曲。而POST /api/music/free2/cached只對本帳號下載過的歌返回位址。- 同一首歌首次解析會生成託管檔案，之後複用；
files裡不要傳重複類型，服務端會自動去重。 - 與歌曲媒體下載與試聽 API 的區別：Free2 是付費、 支援直接傳 suno.com 連結、並且不提供歌詞之外的時間軸/MIDI 等類型。