歌曲媒體下載與試聽 API

2026-09-18 更新 · Suno-API 團隊

介面說明

這一組介面把「拿媒體位址」和「真正下載檔案」分開：

• 想拿一個可以直接播放／下載的位址（例如放進自己的播放器或轉存到物件儲存）：用 POST /api/music/download-url，或回應裡已經給出的 GET /api/music/download。
• 想讓瀏覽器直接落盤保存檔案：用 POST /api/music/download-file（單一檔案）或 POST /api/music/download-all（打包）。
• 歌曲還在生成中、想先試聽：用 POST /api/music/generation-stream-url。

計費：全部免費。下載與試聽只讀取平台已託管的媒體，不呼叫 Suno，不扣費。

推薦模型：suno-v6。可用 suno-v6、suno-v6-wild 或 suno-v6-mini。

驗證

支援的媒體類型（kind）

1）取得媒體位址

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url 用於播放或自行轉存；nav_url 帶 Content-Disposition: attachment， 適合直接賦給瀏覽器網址列下載（部分手機瀏覽器不支援 blob 下載時使用）。

⚠️ 位址有效期：7 天，請及時轉存

url / nav_url 指向平台的物件儲存，預設在 7 天後失效（檔案到期回收，舊位址會回應 404）。請在這 7 天內把檔案轉存到自己的儲存。

過期後不必重新生成歌曲：重新呼叫 POST /api/music/download-url（或把 refresh 傳 true）即可拿到該歌曲新的有效位址，本組介面本身免費、不額外計費。

2）直接下載單一檔案

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

回應主體是檔案串流（不是 JSON），Content-Disposition 已經帶好檔名。 歌詞與時間軸歌詞只能用這個介面取（download-url 只回應媒體位址，不回應歌詞）。 其中 .lrc 檔案目前僅部分歌曲支援；若回應 success:false，請按下一節用 時間軸歌詞 API 自行生成 .lrc，不要重試。

時間軸歌詞（.lrc）怎麼取

建議用兩步，任何歌曲都適用：

第一步：取逐詞時間軸（免費）

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

回應直接就是陣列（沒有 data 外層包裝），每個元素形如 {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}。 word 裡已經帶換行，可按行拆開；欄位含義、器樂段過濾等注意點見 時間軸歌詞 API 的「欄位說明」「使用注意」。

第二步：用 start_s 自行拼 .lrc（時間格式 [mm:ss.cc]）

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc 也可以直接下載伺服器生成的 .lrc， 但目前僅部分歌曲支援：如果回應 success:false，請改用上面這種方式自行生成， 不需要重試、也不影響計費。

3）打包下載

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

song_id（單一）與 song_ids（批次，最多 50 筆）二選一。回應主體是 ZIP 檔案串流。

4）穩定下載位址

GET /api/music/download?song_id=<id>&kind=<kind> 是歌曲回應裡直接給出的下載入口， 驗證同時支援 API Key 與登入態，行為等價於 download-file，適合寫死進用戶端或第三方播放器。

5）生成中試聽

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

playable_until_completed 為 true 表示這是生成中的臨時試聽位址，歌曲完成後請改用正式位址； 單首失敗時該項會帶 error 欄位，其餘歌曲照常回應。

注意事項

• 所有介面都只回應平台託管的媒體位址，不會回應 Suno 平台的加密源或臨時簽名位址。
• 位址不是永久有效的，長期保存請自行轉存；需要原始檔案落盤時用 download-file。
• 分軌軌道的 MIDI 需要該軌道已完成分離，否則回應錯誤。