Suno API

RouteAPI 提供統一的 Suno AI 音樂生成 REST API。支援文字生成音樂、續寫歌曲、聲音複製、音軌分離等功能。

整體工作流程

Suno 音樂生成是非同步的。 典型流程：

提交任務 到 /suno/audios → 收到 task_id
等待 2-3 秒 後開始輪詢
每 3-5 秒輪詢一次 透過 /suno/tasks 使用 action: "retrieve"
當 status 變為 success → 取得 audio_url

任務狀態

狀態	含義	下一步
`submitted`	已提交，等待排隊	繼續輪詢
`queued`	排隊中	繼續輪詢
`in_progress`	生成中	繼續輪詢
`success`	✅ 完成	從 `data` 陣列的第一項取 `audio_url`
`failure`	❌ 失敗	取 `error` 欄位查原因

快速開始

第一步：提交任務

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "一首歡快的夏日流行歌曲，鋼琴和吉他",
    "async": true
  }'

第二步：輪詢任務狀態

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

第三步：取結果

{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "status": "success",
  "data": [
    {
      "id": "audio_1",
      "audio_url": "https://cdn.suno.ai/xxx.mp3",
      "video_url": "https://cdn.suno.ai/xxx.mp4",
      "title": "Summer Breeze",
      "duration": 183.5
    }
  ]
}

支援的模型

模型 ID	最長時長	lyric 上限	style 上限
`chirp-v5-5`	8 分鐘	5000 字元	1000 字元
`chirp-v5`	8 分鐘	5000 字元	1000 字元
`chirp-v4-5-plus`	8 分鐘	5000 字元	1000 字元
`chirp-v4`	150 秒	3000 字元	200 字元

POST /suno/audios

音訊操作的核心介面：action 欄位決定具體操作，請求主體攜帶該操作需要的欄位。

核心參數

欄位	類型	預設值	說明
`model`	string	`chirp-v4`	生成模型，推薦 `chirp-v5-5`
`action`	string	`generate`	操作類型
`async`	boolean	—	強烈建議設為 `true`。只有明確傳 `false` 才走同步分支；省略該欄位時不會轉發，由上游預設值決定

Action 操作類型

Action	說明	必需欄位
`generate`	根據提示詞生成全新音訊	`prompt` 或 `custom=true` + `lyric` + `style`
`extend`	在已有音訊基礎上續寫延長	`audio_id` + `continue_at`
`cover`	複製已有曲目的音樂風格並重新演繹	`audio_id`
`stems`	分離為人聲 + 伴奏兩軌	`audio_id`
`all_stems`	分離為所有獨立音軌	`audio_id`
`remaster`	對已有音訊重新母帶處理以提升音質	`audio_id`
`mashup`	將多首歌曲混合拼接為一首曲目	`mashup_audio_ids`

完整操作類型請參考英文或簡體中文文檔。

示例

描述詞快速生成

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "一首歡快的兒童歌曲",
    "async": true
  }'

自訂歌詞生成

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "custom": true,
    "title": "夏日之歌",
    "style": "流行, 歡快, 輕快",
    "lyric": "[Verse]\n第一段歌詞\n[Chorus]\n副歌部分",
    "async": true
  }'

POST /suno/tasks

查詢任務狀態與結果。

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

其他介面

介面	方法	說明
`/suno/lyrics`	POST	生成歌詞文字
`/suno/upload`	POST	上傳外部音訊檔案
`/suno/persona`	GET/POST	管理語音人格（聲音複製）
`/suno/wav`	POST	匯出 WAV 格式音訊
`/suno/mp4`	POST	匯出 MP4 影片
`/suno/midi`	POST	匯出 MIDI 檔案

完整 API 參考請查看英文或簡體中文文檔。

錯誤處理

請求進入任務處理後，錯誤使用任務回應主體：

{ "code": "invalid_request", "message": "prompt_empty (request id: ...)", "data": null }

認證與路由階段的失敗發生在進入任務處理之前，沿用 OpenAI 風格主體 {"error": {"message": "...", "type": "...", "code": "..."}}。參見常見錯誤。

狀態碼	錯誤碼	原因
400	`invalid_request`	該介面或 action 缺少必填欄位，`message` 會指出欄位（例如 `/suno/lyrics` 的 `prompt_empty`，或 `/suno/vox` 的 `audio_id_vocal_start_vocal_end_required`）
400	`task_not_exist`	`action: "retrieve"` 的 `id` 不屬於你的任務
401	—	API Key 缺少、無效或已過期（OpenAI 風格主體）
403	`insufficient_user_quota`	帳戶餘額或 Key 額度不足以預扣
429	—	上游渠道回報限流或過載；RouteAPI 會替換供應商原文
502	`acedata_suno_request_failed`	上游已受理但拒絕了請求：內容審核阻擋、`audio_id` 不存在、不支援的 action。`message` 帶上游說明
502	`upstream_task_id_missing`	上游回傳 2xx 但沒有任務 ID，任務無法輪詢；預扣費用會退回
503	`get_channel_failed`	任務背後的渠道被判為硬故障（例如上游帳戶不可用）；RouteAPI 會替換供應商原文。（完全沒有渠道的模型會在進入任務處理前就被拒絕，回傳 `503 model_not_found` 與 OpenAI 風格主體）
4xx / 5xx	`fail_to_fetch_task`	上游回傳非 2xx 狀態碼；狀態碼與回應主體原樣傳遞，預扣費用退回

輪詢回傳 failure 的失敗任務同樣會退回預扣費用，失敗原因在任務記錄的 error 與 message 欄位中。

常見問題

Q: 如何選擇模型版本？
優先用 chirp-v5-5（最新最強）。

Q: 生成需要多久？
generate 通常 15-40 秒。處理類操作可能需要 1-3 分鐘。

Q: audio_url 可以直接用嗎？
是的，CDN 直連可直接播放或下載。

Q: 並行請求有限制嗎？
建議並行數 ≤ 5，輪詢間隔 ≥ 3 秒。