快速開始

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

本指南會在約五分鐘內，帶你從建立 API 金鑰走到生成第一首歌、查詢進度並下載音訊。範例可直接 複製執行。

目前的預設模型是 suno-v6。從 suno-v2 到 suno-v5-5 的生成模型已全部下線：舊任務中仍 可能看到它們，但不再接受新請求。

請從這個位址下載安裝設定 suno-api agent kit  https://www.suno-api.io/suno-agent-kit.zip

推薦接入：一句話交給 AI

AI 會閱讀 00_START_HERE.md，協助註冊、保存 API Key、檢查餘額、介紹全部功能並完成第一次生成。收費操作會先確認，逾時不會自動重複送出。

步驟 1：取得 API 金鑰

1. 開啟 https://www.suno-api.io。
2. 點選 取得 API 金鑰 並註冊。只需要電子郵件，不需要手機號碼。
3. 在主控台開啟權杖管理並建立金鑰。
4. 立即複製，金鑰只會顯示一次。首次付費呼叫前，請先用兌換碼儲值。

步驟 2：設定請求

所有呼叫都使用相同的基礎網址與標頭：

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

步驟 3：送出第一個請求

範例 1 — 從描述生成

描述音樂，API 會寫出歌詞、旋律與編曲：

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "一首關於春天第一天的輕快民謠",
    "model": "suno-v6"
  }'

回應：

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "春日故事",
    "description": "一首關於春天第一天的輕快民謠",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "春日步伐",
    "description": "一首關於春天第一天的輕快民謠",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

每次執行會回傳兩個不同版本供你挑選。一次生成 0.6 ¥。

範例 2 — 查詢進度

把回傳的 song_id 送到查詢端點：

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

任務進行中：

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "春日故事",
    "progress": "60%"
  }
]

完成後：

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "春日故事",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

status 會依序經過 pending、submitted、processing，最後抵達 completed。任務進行時網址 可能仍為空，請以 status 判斷，不要以是否有 audio_url 判斷。

步驟 4：下載檔案

當 status 為 completed 時，直接請求 audio_url 即可。MP3 與 WAV 下載不限次數，也不會另外 計費。若剪輯需要無損音訊，請使用 WAV 端點。

⚠️ 音訊網址 7 天後失效。 audio_url（以及 WAV 等媒體連結）由平台的物件儲存提供，請在 7 天內自行轉存到你的儲存空間；過期後舊網址會回傳 404。重新呼叫歌曲查詢 API 就能取得新的有效網址，不需要重新生成，也不會額外計費。

常見情境

影片背景音樂

{
  "description": "適合產品影片的冷靜 lo-fi 背景，無人聲，動態穩定",
  "instrumental": true,
  "model": "suno-v6"
}

把 instrumental 設為 true 時，輸出不含人聲。

自訂歌詞與風格

{
  "lyrics": "[Verse 1]\n城市燈光慢慢熄滅\n\n[Chorus]\n我們繼續前行",
  "style": "acoustic pop, 溫暖女聲, 92 BPM",
  "model": "suno-v6"
}

輪詢直到完成

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "一首關於春天的輕快民謠", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

錯誤處理

主要狀態碼

錯誤格式

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

等待時間與逾時（重要）：生成類介面是同步介面，回應返回時才代表訂單已被受理並提交生成。實測多數請求 1–3 秒返回，約 10% 超過 30 秒，最長約 230 秒。請把用戶端逾時設為 300 秒以上（範例中的 --max-time 300）；未收到回應不等於沒有生成，逾時後請勿立即重試（會重複下單、重複扣費）。 連線中斷可稍後用 GET /api/music/songs 確認。詳見 Suno API 介面文件總覽的「等待時間與逾時設定」。

最佳實務

• 金鑰請保存在伺服器，不要放在瀏覽器或散布出去的應用程式裡。
• 每 10–15 秒查詢一次，不要密集輪詢。
• 保存 song_id，那是日後找回音訊的唯一識別碼。
• 遇到 429 與 500 請重送；遇到 400 與 401 請先修正原因。
• 生成失敗會自動退費，因此失敗的任務不會產生費用。
• 用戶端逾時：生成類介面在回應返回時才算受理完成，請把用戶端逾時設為 300 秒以上。
• 重試：只對明確的失敗回應（4xx/5xx）重試；連線逾時或中斷時，先用 GET /api/music/songs 確認訂單是否已受理，避免重複下單與重複扣費。

下一步

• 認證說明 — 金鑰、錯誤與限制
• 支援的模型 — 模型名稱、分軌與已下線模型