替換段落 API

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

介面說明

替換段落用於對既有歌曲的指定時間段進行局部重新生成，適合修正一句歌詞或替換某個片段。

介面位址：POST /api/music/replace-section

計費：收費，目前預設 0.6 元/次。實際扣費以目前後台價格設定為準。

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 參數

startSeconds、endSeconds 的單位是秒，可以填寫小數；startSeconds 必須小於 endSeconds，並且區間應位於原歌曲時長內。requestedAt 僅在需要傳遞請求時間時使用，單位為 Unix 秒級時間戳，不是毫秒時間戳；通常可以省略。

替換介面也是非同步任務。回傳的 clip 初始狀態可能為 pending，此時音訊位址為空屬於正常現象，請使用回傳的真實 song_id 查詢最終結果。

片段長度：至少 2 秒（重要）

要替換的區間不能短於 2 秒。實測：1.0 / 1.2 / 1.5 秒的區間全部失敗，2.0 秒及以上正常。

區間過短時，平台回的不是「參數錯誤」，而是一句容易被誤讀的提示：

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

這句話不是帳號或方案問題，而是片段太短。把區間拉長到 2 秒以上再提交即可。

請求範例

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "完整上下文歌詞",
    "contextWindowLyrics": "視窗上下文歌詞",
    "infillLyrics": "替換後的歌詞",
    "style": "Mandopop, acoustic",
    "title": "替換版本",
    "negativeTags": "noise"
  }'

回應結果

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "替換版本",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

相容欄位

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags