歌曲查詢與歷史 API

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

本頁包含三類免費查詢介面：

如果你用的是生成介面的受理回執模式（accept_mode=async），拿到的是受理號而不是歌曲 ID， 進度請用 GET /api/music/requests/{request_id} 查詢，拿到真實 song_id 後再回到本頁的介面。 詳見靈感模式生成 API 的「受理回執模式」。

驗證與資料範圍

所有介面使用同一套 API Key 驗證：

Authorization: Bearer YOUR_API_KEY

歌曲歷史依 API Key 所屬的 user_id 隔離。同一主帳號建立的多個 API Key 可以查詢該主帳號的歌曲歷史，但不能查詢其他使用者或子站帳號的歌曲。

歷史歌曲介面只回傳真實生成歌曲，不包含：

• pending: 開頭的生成佔位記錄；
• 上傳源音訊和強化上傳記錄；
• 人聲／伴奏分離、stems 等子結果；
• 其他使用者或子站帳號的歌曲。

一、查詢歌曲生成狀態

用於根據一個或多個歌曲 ID 查詢目前生成狀態與最終結果。

介面位址：POST /api/music/query

計費：免費。

Headers

Body 參數

請求範例

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

回應範例

[
  {
    "song_id": "clip_id_1",
    "song_title": "歌曲標題",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "歌詞內容",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

相容說明

舊版文件中的 song_ids 可能寫成陣列。新版建議使用逗號分隔字串，與目前介面呼叫方式一致。

song_ids 必須是真實歌曲 ID。pending: 開頭的佔位 ID 不是最終 song_id，不能用於本介面；只查詢佔位 ID 時可能回傳空陣列 []。

查詢回應中的 model、model_version 或平台 model_name 可能保留歷史值。目前新任務應使用 suno-v6、suno-v6-wild 或 suno-v6-mini；suno-v2 至 suno-v5-5 已下線，歷史記錄出現這些名稱不代表可以繼續提交對應模型。

生成任務處於 pending、submitted 或 processing 時，audio_url、video_url 和 cover_url 可能為空，這是任務尚未完成的正常表現。不要只依位址為空判斷失敗；請配合 status 判斷，並在狀態完成後再次查詢。只有狀態完成且位址仍為空時，才建議聯絡技術支援並提供 song_id。

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

本介面回傳的 audio_url、video_url（以及 WAV 等其它媒體位址）由平台物件儲存提供，預設在 7 天後失效：到期後檔案被回收，再用舊位址存取會回傳 404。

• 請在 7 天內把檔案轉存到你自己的儲存，不要把它當作長期可用的連結。
• 位址過期不需要重新生成歌曲、也不會再次計費：重新呼叫本介面（POST /api/music/query）即可拿到該歌曲新的有效位址。

二、查詢帳號歌曲歷史

查詢目前 API Key 所屬主帳號已經生成的歌曲，適合建立使用者自己的歌曲清單、選擇器或歷史記錄頁面。

介面位址：GET /api/music/songs

計費：免費。

Query 參數

結果依 created_at、內部記錄 ID 倒序排列，確保翻頁順序穩定。

提交逾時後的找回方式：生成類介面在受理前不會有中間回應。如果用戶端在提交時逾時或中斷了連線，這一單可能已經受理並生成了歌曲。請用本介面依時間倒序看一眼，已受理的歌曲會正常出現在清單裡；確認確實沒有，再重新提交，避免重複扣費。詳見 Suno API 介面文件總覽的「等待時間與逾時設定」。

請求範例

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "夜色中的城市",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

回傳欄位

清單介面不會回傳提示詞、計費欄位、帳號資訊或原始回應。需要提示詞和生成參數時，請呼叫歌曲詳情介面。

三、查詢歌曲生成參數

依歌曲 ID 查詢該歌曲生成時由平台留存的提示詞、風格、模型和來源歌曲等參數。

介面位址：GET /api/music/songs/:song_id

計費：免費。

只能查詢目前 API Key 所屬主帳號的歌曲。其他使用者或子站帳號的歌曲一律以「歌曲不存在」處理。

路徑參數

請求範例

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "夜色中的城市",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "雨後的城市街道，關於重逢的歌詞",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "夜色中的城市",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

parameters 欄位

prompt_view 欄位（檢視提示詞，2026-09-28 新增）

prompt_view 是「檢視提示詞」專用的正規化結構：依生成類型把資料組織成固定分區， 用戶端不用再自己判斷哪個欄位該顯示。它是純新增欄位——舊欄位（parameters、 parameter_retention）名稱與含義不變，不解析新欄位的用戶端完全不受影響。

"prompt_view": {
  "type": "custom_generate",
  "type_label": "專業模式",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "凌晨四點#701f37", "title_base": "凌晨四點", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "……", "user_text_kind": "lyrics",
    "user_style": "國潮電子, 重低音貝斯, 復古合成器",
    "style_tags": "國潮電子, 重低音貝斯, 復古合成器",
    "style_source": "user", "lyrics": "……",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

extended 可能出現的欄位：vocal_gender、style_weight、audio_weight、 weirdness_constraint、variety、lyrics_mode、custom_mode，以及音效類的 sound_type / sound_bpm / sound_key / sound_loop。空值一律不回傳。

三條顯示規則（用戶端依這個做，不要自己推斷）：

1. 風格來源要區分：style_source=suno_derived 時請顯示成 「風格（Suno 依你的描述歸納）」，不要寫成「你填的風格」；
2. 內部提示詞不會出現：音色翻唱類只回傳使用者自己填的【風格要求】／【翻唱要求】， 我們拼給模型的固定結構段不會出現在任何欄位裡（歷史資料同樣已脫敏）；
3. 沒留存的參數不猜：extended 裡沒有就是當時沒記錄，用 retention 向使用者解釋原因。

參數留存說明

parameter_retention 用於區分「明確傳入了空值」和「歷史上沒有保存該欄位」：

• core_parameters_available：主歌曲任務記錄是否存在，正常詳情固定為 true；
• extended_parameters_available：是否找到了關聯的擴充音樂任務記錄；
• sources：本次參數來自哪些資料表；
• unavailable_fields：無法從歷史資料可靠復原的欄位，這些欄位在 parameters 中回傳 null。

一般歷史歌曲通常保存了提示詞、風格、目前標題、模型、生成類型和來源歌曲，但沒有獨立保存全部進階參數。平台不會依 generation_type 猜測缺失值。

部分擴充音樂任務還保存了原始提示詞、風格、標題、模型，以及 custom_mode、negative_tags、vocal_gender、style_weight、weirdness_constraint。即使存在擴充記錄，instrumental、lyrics_mode 和 wait_audio 仍可能無法復原。

歌曲標題可以被使用者後續重新命名。一般歷史任務沒有單獨保存原始標題時，parameters.title 可能是目前標題；存在擴充任務記錄時，會優先回傳擴充記錄保存的原始生成標題。

不存在或無權限

業務錯誤使用統一回應信封。歌曲不存在或不屬於目前帳號時回傳：

{
  "success": false,
  "message": "song not found"
}

該業務錯誤目前使用 HTTP 200 回傳，請以 success 欄位判斷結果。API Key 缺失、無效、過期或被停用時回傳 HTTP 401。

安全說明

歌曲歷史和詳情介面不會回傳：

• API Key、Token ID；
• 額度、計費或退款欄位；
• 帳號資訊和原始回應；
• 物件儲存內部鍵；
• 管理員錯誤和內部資源錯誤。