Replace Section API（区間の置き換え）

2026-09-18 更新 · Suno-API チーム

インターフェースの説明

区間の置き換えは、既存の楽曲の指定した時間帯を部分的に再生成します。1 行の歌詞を直したり、あるフレーズを差し替えたりするのに向いています。

エンドポイント: POST /api/music/replace-section

課金: 有料、現在は既定で 1 回 0.6 元。実際の請求額は現在の管理画面の価格設定に従います。

Max Mode / Variety: 本エンドポイントは任意パラメータ max_mode と variety（0〜4）に対応しています。 max_mode を有効にするとこの 1 回は 2 倍の価格で課金され（0.6 → 1.2 元/回）、variety に追加課金は ありません。両者の意味と書き方は新版 API 概要の「高度なパラメータ」の節をご覧ください。

待ち時間とタイムアウト（重要）: 本エンドポイントは同期インターフェースで、レスポンスが返った時点で初めて注文が受理され生成に投入されます。実測では多くのリクエストが 1〜3 秒で返り、約 10% が 30 秒を超え、最長は約 230 秒です。クライアントのタイムアウトは 300 秒以上に設定してください。レスポンスが無いことは未生成を意味せず、タイムアウト直後の再試行は注文の重複と二重課金につながります。 接続が切れた場合は少し後に GET /api/music/songs で確認できます。詳しくは新版 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