認證說明

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

所有送往 Suno-API 的請求都以 API 金鑰認證。本頁說明如何建立金鑰、如何送出、各種錯誤的意義， 以及如何安全保存金鑰。

什麼是 API 金鑰

金鑰是綁定在你帳號上的 bearer 權杖，並承載餘額，因此拿到金鑰的人就能動用餘額。金鑰在建立時 只顯示一次：請複製並保存在安全的地方。

建立金鑰

1. 在 https://www.suno-api.io 註冊——只需電子郵件，不需要手機號碼。
2. 在主控台開啟權杖管理。
3. 建立新金鑰並複製。

金鑰格式為 sk-…。遺失的金鑰無法復原：請建立新的並刪除舊的。

使用金鑰

請求標頭格式

每次請求都在 Authorization 標頭帶上金鑰：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

範例

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "一首適合咖啡店的平靜鋼琴曲"}'

認證錯誤

401 Unauthorized

標頭缺少、格式錯誤，或金鑰不存在。

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

請確認標頭正好是 Bearer <金鑰>（Bearer 後有一個空格），且金鑰尾端沒有夾帶換行字元。

403 Forbidden

金鑰存在，但這次請求不被允許。最常見的原因是金鑰已停用或帳號已暫停。請在控制台確認帳號狀態，原因不明時請聯絡技術支援。

安全最佳實務

不要把金鑰放進前端程式碼

不要將金鑰內嵌在網頁、行動應用或桌面程式中。任何能開啟瀏覽器開發者工具的人都能讀到它並花掉 你的餘額。請從自己的伺服器呼叫 API，只把自己伺服器的端點提供給使用者。

使用環境變數

Linux / macOS

# ~/.bashrc 或 ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# Python
import os
api_key = os.environ["SUNO_API_KEY"]

.env

# .env 檔——請加入 .gitignore
SUNO_API_KEY=sk-your-key-here

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

需要時更換金鑰

金鑰建議每 3–6 個月更換一次，懷疑外洩時立即更換。不再使用的金鑰請刪除，沒在用的金鑰只等於沒在用的風險。

請求頻率限制

請求依金鑰分別限流：

429 Too Many Requests

超過限制時 API 會回傳 429，回應可能帶有 retry_after（秒）。請等待該秒數後再試，並以降低請求頻率、排入佇列或指數退避等方式分散負載，不要緊迴圈重送。

重試策略

只對明確的失敗重試。讀取逾時或連線逾時後請勿重試：生成類介面是同步介面，逾時也可能代表訂單已受理並在生成；重試會重複下單、重複扣費。請把用戶端逾時設為 300 秒以上，連線中斷時先用 GET /api/music/songs 確認訂單是否已受理再決定是否重送。詳見 Suno API 介面文件總覽的「等待時間與逾時設定」。

請以指數退避重送，而不是密集輪詢：

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

常見問題

金鑰的格式是什麼？

以 sk- 開頭，後面接英數字，總長約 50–60 個字元。

可以直接從瀏覽器呼叫 API 嗎？

技術上可以，但正式環境不要這樣做，因為所有訪客都看得到金鑰。請透過自己的後端代理。

如何確認金鑰仍然有效？

送出任一個已認證的請求。200 表示可用；401 表示金鑰無效或已刪除。

金鑰遺失了怎麼辦？

金鑰無法復原。請在主控台建立新的並刪除舊的。

一個帳號可以有幾把金鑰？

沒有固定上限。建議每個應用或環境各用一把，方便單獨撤銷，不再使用時刪除。

金鑰會過期嗎？

在你刪除或關閉帳號之前都有效。定期更換是良好做法。

如何追蹤用量？

登入控制台即可查看每把金鑰的使用情況（請求次數、消費金額、近期任務）。

相關頁面

• 快速開始指南
• 支援的模型