專業模式生成 API

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

介面說明

專業模式適合已經準備好歌詞、風格和標題，並希望控制演唱聲音、風格參考強度和生成隨機度的情境。

介面位址：POST /api/music/create/custom

計費：收費，目前預設 0.6 元/次。每次通常回傳 2 首歌曲，實際扣費以目前後台價格設定為準。

Max Mode / Variety：本介面支援選用參數 max_mode 與 variety（0-4）。開啟 max_mode 時本次依 2 倍價格計費（0.6 → 1.2 元/次），variety 不額外計費；兩者含義與寫法見 Suno API 介面文件總覽 的「進階參數」一節。

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

請求參數

Headers

Body 參數

進階參數說明

聲音性別 vocal_gender

• 男聲傳 m 或 male，女聲傳 f 或 female。
• 伺服器會將 male、female 分別正規化為 m、f。
• 當 instrumental=true 時，不會向生成服務發送聲音性別參數。

風格參考度 style_weight

控制生成結果對 style_tags 的參考強度。值越高，生成結果通常越傾向遵循所填寫的風格標籤。

隨機度 weirdness_constraint

控制生成結果的變化和實驗性傾向。值越高，結果通常越有變化；值越低，結果通常越穩妥。

兩個數值參數的範圍均為 0.0 到 1.0，其中 0 是有效的明確值。只有完全不傳欄位時，才表示不指定該項。

填寫時請注意：這兩個參數是比例小數，不是百分比整數。推薦參考：0.0 到 0.3 偏保守，0.4 到 0.6 較均衡，0.7 到 1.0 更偏實驗性；沒有明確偏好時可使用 0.5，也可以直接省略。範例：weirdness_constraint: 0.5，不要填寫 50 或 50%。

instrumental=true 時會生成純音樂，歌詞和聲音性別不會按人聲歌曲方式生效；如需要人聲，請傳 false 或省略該欄位。布林欄位必須使用 JSON 的 true/false，不要使用字串。

Python 請求範例

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\n夜色落在海面上\n晚風輕輕經過窗',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': '海邊的晚風',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

受理回執模式（選用）

本介面同樣支援靈感模式生成 API 裡的受理回執模式：請求內容加 "accept_mode": "async"（或請求標頭 X-Accept-Mode: async）時，介面立刻回傳 202 和受理號， 生成在後台繼續，用 GET /api/music/requests/{request_id} 查詢進度。

適用於用戶端不適合掛長連線、或不想因為逾時誤判「沒有生成」的情境。不帶該參數時行為與以前完全一致。

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "海邊的晚風",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

回傳結構與輪詢方式見靈感模式生成 API 的「受理回執模式」一節。

參數驗證

以下情況會回傳 HTTP 400，錯誤回應的 message 會指出無效欄位：

• style_weight 或 weirdness_constraint 不是數字。
• 數值小於 0.0 或大於 1.0。
• vocal_gender 不是 m、f、male、female 之一。

文字欄位長度上限

以下欄位超長同樣回傳 HTTP 400，且不會進入生成、不會預扣費。計數依 Unicode 字元（一個漢字算 1 個字元），首尾空格也計入：

錯誤訊息形如 style_tags must not exceed 1000 characters; received 2772：第一個詞是超限的欄位名，末尾是實際字數，拿到 400 直接依這兩個數字裁剪即可，不用逐個欄位試。通用約定見 Suno API 介面文件總覽的「文字欄位長度上限」。

回應結果

介面通常回傳包含 2 首歌曲的陣列。非同步請求初始狀態一般為 pending，請保存 song_id，並透過歌曲查詢 API取得最終狀態和音訊位址。歌曲欄位同靈感模式生成 API。

相容欄位

新接入請統一使用 snake_case。若同一請求同時傳入 snake_case 和 camelCase，snake_case 的值優先。