Replace Section API

Updated 2026-09-18 · Suno-API team

Endpoint description

Replace Section regenerates one time range of an existing song in place. It suits fixing a line of lyrics or swapping out a passage.

Endpoint: POST /api/music/replace-section

Billing: Paid, currently 0.6 ¥ per call by default. The amount actually charged follows the current back-office price configuration.

Max Mode / Variety: this endpoint supports the optional parameters max_mode and variety (0-4). With max_mode on, this call is billed at 2× the price (0.6 → 1.2 ¥ per call); variety costs nothing extra. What they mean and how to send them is in the "Advanced parameters" section of the New API overview.

Wait times and timeouts (important): this is a synchronous endpoint — the order is only accepted and handed to generation when the response arrives. Measured, most requests return in 1-3 seconds, about 10% take longer than 30 seconds, and the longest is about 230 seconds. Set your client timeout to 300 seconds or more; no response does not mean nothing was generated, and do not retry immediately after a timeout (that duplicates the order and charges again). If the connection dropped, confirm later with GET /api/music/songs. See "Wait times and timeout settings" in the New API overview.

Request parameters

Headers

Body parameters

startSeconds and endSeconds are in seconds and accept decimals; startSeconds must be less than endSeconds, and the range should lie within the original song's duration. requestedAt is only used when you need to pass a request time, as a Unix timestamp in seconds (not milliseconds); it can normally be omitted.

Replacement is an asynchronous task as well. The returned clip may start in pending, and an empty audio address at that point is normal; use the real song_id that comes back to query the final result.

Section length: at least 2 seconds (important)

The range to replace cannot be shorter than 2 seconds. Measured: ranges of 1.0 / 1.2 / 1.5 seconds all failed, while 2.0 seconds and above worked.

When the range is too short, the platform does not answer with a "parameter error" but with a message that is easy to misread:

{"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"}}

That sentence is not an account or plan problem — the section is too short. Lengthen the range past 2 seconds and submit again.

Request example

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": "full context lyrics",
    "contextWindowLyrics": "window context lyrics",
    "infillLyrics": "replacement lyrics",
    "style": "Mandopop, acoustic",
    "title": "Replaced version",
    "negativeTags": "noise"
  }'

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Replaced version",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Compatible fields

• 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