認證說明

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

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

什麼是 API 金鑰

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

建立金鑰

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

金鑰格式為 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，只把自己伺服器的端點提供給使用者。

使用環境變數

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

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

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

需要時更換金鑰

若懷疑外洩，請建立替代金鑰並刪除舊的。更換金鑰成本很低，外洩的金鑰則不是。

請求頻率限制

請求以金鑰為單位限制。超過限制時 API 會回傳 429 Too Many Requests。

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

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- 開頭，後面接一段隨機字串。請把整個值當作單一權杖。

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

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

如何確認金鑰仍然有效？

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

金鑰遺失了怎麼辦？

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

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

可以有多把。建議每個應用或環境各用一把，方便獨立撤銷。

金鑰會過期嗎？

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

如何追蹤用量？

餘額與紀錄都在主控台。每次生成 0.6 ¥ 並回傳兩首，失敗會自動退費。