Suno API 介面文件總覽

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

用 Email 註冊就能建立 API Key，生成介面每次 0.6 元、回傳 2 首歌，支援 MP3/WAV 下載、翻唱、續寫、分軌與人聲複製；介面網址基底為 https://www.suno-api.io。

本頁說明目前可用的模型、全部生成與編輯介面、計費方式與建議的接入順序；新接入建議照這裡的順序往下讀，遇到 401/403/429 也有對應的排查入口。

常見問題速查

API Key 怎麼取得？ 用 Email 註冊後進入主控台 → 權杖管理，新增一個權杖即可，不需要手機號碼，也不用綁卡。

每次多少錢？ 生成介面每次 0.6 元、回傳 2 首歌；查詢狀態、WAV、時間軸歌詞、提示詞建議等介面不另外收費。

支援哪些模型？ suno-v6（預設）、suno-v6-wild、suno-v6-mini；v5.5 及更早的一般生成模型已下線，歷史作品不受影響。

介面網址是什麼？ https://www.suno-api.io，請求標頭帶 Authorization: Bearer YOUR_API_KEY。

目前支援的模型

一般歌曲生成介面開放給客戶的模型只有 suno-v6、suno-v6-wild 與 suno-v6-mini，不填 model 時預設使用 suno-v6。

一般模型 suno-v2、suno-v3、suno-v3-5、suno-v4、suno-v4-5、suno-v4-5-all、suno-v4-5-plus、suno-v5、suno-v5-5 已下線。查詢歷史任務時仍可能看到舊模型名稱，這只代表歷史資料，不代表舊模型仍可用於新的請求。分軌介面是例外，詳見分軌（人聲伴奏分離）API。

驗證方式

所有對外 API Key 介面統一使用：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

介面網址基底：

https://www.suno-api.io

一般參數填寫約定

• 請求內容中的 number 必須傳 JSON 數字，不能傳百分比字串。例如強度 50% 應寫成 0.5，不能寫成 50 或 50%。
• 請求內容中的 boolean 必須傳 true 或 false，不要傳 true、false、0、1 等替代值。
• 標示為「否」的欄位可以完全不傳。不確定參數含義時，優先省略欄位，讓服務使用預設行為；不要用空字串、null 或 0 代替「未傳」，因為 0 在部分數值欄位中是有效值。
• 欄位名稱區分拼寫。各介面文件會列出建議欄位與相容欄位；新接入請照參數表原樣傳遞。若文件說明 snake_case 與 camelCase 同時相容，兩者不要同時傳。
• 所有以 _s、Seconds 結尾的時長欄位單位均為秒，可以使用小數；Unix 時間戳會另外註明是秒級還是毫秒級。
• pending: 開頭的 ID 是平台佔位 ID，不是真實歌曲 ID。只有介面明確說明支援佔位 ID 時才能使用，否則應等待回傳真實的 song_id。

文字欄位長度上限

文字欄位超過上限會直接回傳 HTTP 400：不會進入生成、不會預扣費用、也不會產生任務記錄。計數以 Unicode 字元為準（一個中文字算 1 個字元），開頭與結尾的空白也計入。

超過上限時的 message 會直接給出欄位名稱與實測字數，照這兩個數字修剪即可定位：

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

適用介面：/api/music/create、/api/music/create/custom、/api/music/extend、/api/music/upload-cover、/api/music/generate-from-source、/api/music/add-instrumental、/api/music/add-vocal、/api/music/add-stem、/api/music/mashup、/api/music/sample、/api/music/inspo、/api/music/crop、/api/music/remove-section、/api/music/fade、/api/music/reverse、/api/music/speed、/api/music/replace-section、/api/music/generate-with-voice。

唯一例外：POST /api/music/sounds 的 description（音效描述）上限是 100 字元，走的是平台較短的那條限制。

非同步生成與音訊網址

音樂生成介面預設以非同步方式運作。第一次回應中的 status 為 pending、submitted 或 processing 時，audio_url、video_url、cover_url 為空是正常現象，不代表任務失敗。請保存真實的 song_id 或介面回傳的 client_request_id，照對應的查詢文件輪詢；只有狀態完成後才讀取與下載音訊網址。

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

audio_url、wav_url、video_url 以及各下載介面回傳的網址，都由平台的物件儲存提供，預設在 7 天後失效（檔案到期會被回收，繼續用舊網址存取會回傳 404 / 無法下載）。

• 請在拿到網址後 7 天內把檔案轉存到你自己的儲存空間（自有物件儲存、CDN、伺服器磁碟皆可），不要把我們的網址當成長期連結使用。
• 網址過期不需要重新生成歌曲、也不會產生額外費用：重新呼叫歌曲查詢 API（或媒體下載 API）即可拿到該歌曲新的有效網址。

等待時間與逾時設定

生成類介面是同步介面：只有在回應回傳時，訂單才算被受理並提交給平台生成。在此之前伺服器需要先完成帳號調度與必要的安全驗證，這個過程不會有任何中間回應，也不會有其他介面能查到這一筆。因此判斷「有沒有生成」的唯一依據是回應本身，而不是等待過程中觀察到的任何現象。

實測等待時間（2026-09-18 ~ 2026-09-20 生產環境 /api/music/create 系列）

• 約 10% 的請求需要等待 30 秒以上，約 1% 需要 1–2 分鐘。等待時間偏長的請求，通常是這次需要先通過一次安全檢查。
• 請求欄位、回傳結構、錯誤碼與計費方式都沒有變化，既有接入方只需要調整客戶端逾時設定，不需要修改其他程式碼。

接入要求

1. 客戶端逾時請設定為 300 秒以上。預設 30 秒、60 秒、120 秒的客戶端會在等待期間主動斷線。
2. 未收到回應不等於沒有生成。 連線逾時或中斷時，訂單可能已經受理並正在生成。
3. 逾時後不要立即重試：重複提交會產生新訂單並再次扣費。
4. 如果連線中斷，請稍後用 GET /api/music/songs 依時間倒序查詢；已受理的訂單會正常出現在清單裡。確認確實沒有，再重新提交。
5. 回報問題時請附上回應標頭裡的 X-Oneapi-Request-Id，方便直接定位到這一次請求。

不想掛長連線？用受理回執模式。 POST /api/music/create 與 POST /api/music/create/custom 支援選用的受理回執：請求內容加上 "accept_mode": "async"（或請求標頭 X-Accept-Mode: async），介面立刻回傳 202 與受理號，生成在背景繼續，用 GET /api/music/requests/{request_id} 查進度。這樣客戶端即使只有幾十秒逾時也不會誤判「沒有生成」、也不會因為重試而重複扣費。詳見靈感模式生成 API 的「受理回執模式」。

參考：python requests 用 timeout=300，urllib 用 urlopen(..., timeout=300)，Node 用 req.setTimeout(300000)，curl 用 --max-time 300。

建議介面清單

以上 /api/voice/clone/* 與 /api/music/generate-with-voice 屬於早期人聲複製鏈路，不建議新接入， 請改用【推薦】複製音色 API。

進階參數：Max Mode 與 Variety

生成類介面都支援這兩個選用參數（不傳等於維持原本的行為與價格）：

支援這兩個參數的介面：POST /api/music/create、POST /api/music/create/custom、 POST /api/music/extend、POST /api/music/upload-cover、POST /api/music/generate-from-source、 POST /api/music/add-instrumental、POST /api/music/add-vocal、POST /api/music/add-stem、 POST /api/music/mashup、POST /api/music/sample、POST /api/music/inspo、 POST /api/music/replace-section、POST /api/music/voice-profile/cover、POST /api/music/speech。

• max_mode 的 2 倍價格示例：預設 0.6 元/次的介面開啟後為 1.2 元/次； 指定人聲生成 預設 1.2 元/次，開啟後為 2.4 元/次； 【推薦】複製音色 API 的音色翻唱同樣是 1.2 元/次（開啟 max_mode 為 2.4 元/次）。
• variety 只對 suno-v6 系列（suno-v6、suno-v6-wild、suno-v6-mini）有效， 其他模型傳了會回傳 400。
• 音效生成、分軌、拼接、WAV、Studio 編輯類動作（裁剪、刪減、淡入淡出、倒放、變速等） 沒有這兩個參數，明確傳入會回傳 400，避免「傳了但沒生效」。
• variety 是 0-4 的整數原值，與 style_weight、weirdness_constraint（0-1 小數）量綱不同。

一般歌曲回傳欄位

音樂生成、翻唱、續寫、分離、查詢等介面通常回傳歌曲陣列，常用欄位如下：

接入四步（最小可用示例）

新接入照這四步走一遍就能拿到第一首歌；每一步的完整欄位見「建議介面清單」裡對應的文件頁。

# 1) 提交生成：0.6 元一次，回傳 2 首
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "明亮的中文流行，鋼琴前奏，溫暖女聲", "model": "suno-v6"}'

# 2) 輪詢任務：直到 status 變成 completed（建議 3-5 秒一次）
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "第 1 步回傳的 song_id"}'

# 3) 取媒體網址：讀取類介面免費，可指定 song / wav / video / cover / midi
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"}'

出問題時的排查入口：401 / 402 / 403 / 429 見錯誤清單；逾時與重複扣費見上面的「等待時間與逾時設定」；介面逐個說明見下面的「建議介面清單」。

呼叫建議

• 新接入客戶建議統一使用 suno-v6。
• 標示預設價格的介面，實際扣費以目前後台價格設定與請求模型為準。
• 生成類介面通常會先回傳任務，再透過 /api/music/query 查詢最終音訊。
• wait_completion=true 會阻塞等待，適合低頻測試；生產環境更建議非同步查詢。
• 生成類介面可能需要等待較長時間才回傳，請把客戶端逾時設為 300 秒以上，並注意「未收到回應」不等於沒有生成，詳見上面的「等待時間與逾時設定」。
• 上傳、翻唱、替換、WAV 等能力依賴平台帳號與來源 clip 權限，失敗時請優先查看回傳的 message 或 error_message。

版本說明

本文件依目前 Create UI 已接入能力重新整理，建議新接入客戶優先閱讀本章節。舊版介面文件仍保留在「舊版介面文件（相容）」章節，老客戶可以繼續照原本的方式呼叫。