Music GenerationtaskType: replace_section15 Credits / Task

Replace Music Section

Target and regenerate a specific chorus, bridge, or verse without altering the rest of the song. Intelligently performs audio inpainting, blending newly synthesized lyrics and melodies seamlessly with the preceding and following stems.

POST/api/v1/createTask

Test in Playground

How Section Replacement (Infill) Works

Surgical Inpainting

Specify start and end markers (infill_start_s and infill_end_s) to rewrite only the targeted segment while locking the rest of the audio.

Acoustic Continuity

Automatically cross-fades chord progressions, tempo transitions, and vocal timbres at the section boundaries for a natural finish.

Lyrical Context Flow

Pass full_lyrics alongside your replacement section lyrics so the AI understands song structure and rhyming context.

Supported AI Models

V6, V6_WILD, V6_MINI, V4

V6DEFAULT

Best-in-class natural vocal articulation, pristine audio clarity, and smoother section transitions.

V6_WILDEXPERIMENTAL

Explores bolder chord changes, unexpected vocal ad-libs, and experimental production styles.

V6_MINIFAST

Lightweight and rapid generation for quick section iterations and drafting alternative hooks.

Validation Rules & Constraints

Time Range Rules (Infill Timing)

infill_start_s must be strictly less than infill_end_s.
Time values must be precise up to 2 decimal places (e.g., 10.50 seconds).
The replacement section span (infill_end_s - infill_start_s) must be at least 10 seconds.
Recommended replacement length should not exceed 50% of the original track's total duration.

Identifiers & Text Constraints

task_id and audio_id must match an existing generation task created in your workspace.
V6 / V6_WILD / V6_MINI: Prompt / Lyrics ≤ 5,000 chars, Tags ≤ 1,000 chars, Title ≤ 100 chars.
V4: Prompt ≤ 3,000 chars, Tags ≤ 200 chars, Title ≤ 80 chars.
Generated output tracks are stored on high-speed CDN and retained for 14 days.

Variety & Stylistic Controls (0 - 4)

0: Off

Strict adherence to exact original tags and rhythm.

1: Balanced (Default)

Harmonizes stability with fresh musical variations.

2: High

Pronounced variation in instrumental energy and hooks.

3: Extra

Bold departure from previous melodies and dynamics.

4: Max

Maximum divergence; radically reinterprets the section.

Authentication & Headers

Header	Requirement	Description
Authorization	required	Bearer YOUR_API_KEY Secret API Key obtained from your Suno API dashboard.
Content-Type	required	application/json Request payload format.

Header

Requirement

Description

Authorization

required

Bearer YOUR_API_KEY

Secret API Key obtained from your Suno API dashboard.

Content-Type

required

application/json

Request payload format.

Request Body Schema

20 fields

task_idstringrequired

Unique identifier of the original generation task containing the audio track to edit.

audio_idstringrequired

Unique UUID of the specific audio track within the generation task to modify.

promptstringrequired

Description of desired audio, replacement lyrics, style nuances, or mood for the regenerated section. Max 5,000 characters for V6, max 3,000 for V4.

infill_start_snumberoptional

Start timestamp in seconds for the section to replace. Precise to 2 decimal places (e.g., 30.50). Must be strictly less than infill_end_s.

infill_end_snumberoptional

End timestamp in seconds for the section to replace. The replacement duration (infill_end_s - infill_start_s) must be at least 10 seconds.

modelstringoptional

default:V6

Suno AI generation model version: "V6" (Default, refined details & natural vocals), "V6_WILD" (experimental deviation), "V6_MINI" (fast & lightweight), or "V4".

taskTypestringoptional

default:replace_section

Task routing identifier. Explicitly set to "replace_section". Can also be auto-detected when infill_start_s or infill_end_s is provided.

titlestringoptional

Title for the regenerated music track (max 100 characters for V6, 80 for V4).

tagsstringoptional

Musical style tags or instrumentation keywords for the replacement section (e.g., "Acoustic Pop, Soaring Vocals, 120 BPM"). Max 1,000 characters for V6.

negative_tagsstringoptional

Genres, instruments, or acoustic traits to exclude from the replacement section.

full_lyricsstringoptional

Full lyrics including the replaced section to maintain thematic and lyrical flow across the whole song.

lyricsstringoptional

Custom lyrics specific to the replaced section (verses, chorus, bridge). Takes priority over prompt as lyrics.

vocal_genderstringoptional

Vocal gender preference: "m" for male, "f" for female (increases probability).

style_weightnumberoptional

default:0.65

Strength of adherence to specified style tags (range 0.0 to 1.0, up to 2 decimal places).

weirdness_constraintnumberoptional

default:0.65

Creative/experimental deviation control (range 0.0 to 1.0, up to 2 decimal places).

audio_weightnumberoptional

default:0.65

Balance weight for original audio features vs newly regenerated elements (range 0.0 to 1.0).

varietynumberoptional

default:1

Diversity and stylistic variation: 0 (exact match), 1 (normal / balanced, default), 2 (high diversity), 3 (extra exploration), 4 (max variation).

persona_idstringoptional

Persona ID or Suno Voice ID to maintain vocal character consistency with the original track.

persona_modelstringoptional

default:style_persona

Persona model type: "style_persona" for Persona IDs, or "voice_persona" for Voice IDs.

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notifications across text, first, and complete generation stages.

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

Infill section prompt analysis parsed (callbackType: "text")
First regenerated variation completed & stream ready (callbackType: "first")
All regenerated variations ready with full song audio (callbackType: "complete")
Task failed, time range invalid, or moderation error (code: 400, 408, 500, 501)

Webhook Payload Format

Response Body(200 status)

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "7a3b4c81ef23456789abcdef01234567",
    "data": [
      {
        "id": "r123bcde-5678-4901-abcd-ef0123456789",
        "audio_url": "https://cdn.example.com/audio/inpaint_variation_1.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/inpaint_stream_1.m3u8",
        "image_url": "https://cdn.example.com/cover/inpaint_cover_1.jpeg",
        "prompt": "[Chorus] Soaring through the night skies above...",
        "model_name": "chirp-v4-5",
        "title": "Midnight Serenade (Remastered Chorus)",
        "createTime": 1786346200000,
        "duration": 198.44,
        "tags": "synthpop, emotional, female vocals, 122 bpm",
        "source_audio_url": "https://cdn.example.com/audio/original_track.mp3",
        "source_image_url": "https://cdn.example.com/cover/original_cover.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/original_stream"
      },
      {
        "id": "r234cdef-6789-5012-bcde-f0123456789a",
        "audio_url": "https://cdn.example.com/audio/inpaint_variation_2.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/inpaint_stream_2.m3u8",
        "image_url": "https://cdn.example.com/cover/inpaint_cover_2.jpeg",
        "prompt": "[Chorus] Soaring through the night skies above...",
        "model_name": "chirp-v4-5",
        "title": "Midnight Serenade (Remastered Chorus)",
        "createTime": 1786346200000,
        "duration": 198.44,
        "tags": "synthpop, emotional, female vocals, 122 bpm",
        "source_audio_url": "https://cdn.example.com/audio/original_track.mp3",
        "source_image_url": "https://cdn.example.com/cover/original_cover.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/original_stream"
      }
    ]
  }
}

Callback Payload Fields

Field	Type	Description
`code`	integer	Status code (200: Success, 400: Validation error, 408: Timeout, 500: Server error, 501: Synthesis failed).
`msg`	string	Execution message ("All generated successfully." or specific error reason).
`data.callbackType`	string	Generation progress stage: "text" (cue parse), "first" (track 1 ready), or "complete" (all tracks ready).
`data.task_id`	string	Unique task identifier corresponding to the taskId returned upon creation.
`data.data[]`	array	Array of 2 regenerated audio tracks containing MP3 download URLs, HLS stream URLs, and metadata.
`data.data[].audio_url`	string	Direct high-fidelity MP3 URL for the entire song with the replaced section seamlessly blended in.
`data.data[].duration`	number	Exact duration of the generated full track in seconds.

Receiver Implementation Example

Webhook Receiver

// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if (code === 200 && data) {
    const { callbackType, task_id, data: tracks } = data;
    console.log(`Received ${callbackType} callback for replace-section task ${task_id}`);

    if (callbackType === 'complete' && Array.isArray(tracks)) {
      tracks.forEach((track, index) => {
        console.log(`Variation ${index + 1}: ${track.title} - ${track.audio_url}`);
        // Store updated audio files in your database...
      });
    }
  } else {
    console.error(`Replace section failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Request Sample

curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "replace_section",
    "task_id": "5c79b182e0a4401fa9c6691456a02b11",
    "audio_id": "8ca376e7-5678-4901-abcd-08aaf2c6dd27",
    "prompt": "[Chorus]\nSoaring through the night skies above,\nFinding all the memories we love.",
    "infill_start_s": 35.00,
    "infill_end_s": 55.00,
    "title": "Midnight Serenade (Remastered Chorus)",
    "tags": "Synthpop, Emotional, Female Vocals, 122 BPM",
    "model": "V6",
    "vocal_gender": "f",
    "variety": 1,
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'

Response Body(200 status)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7a3b4c81ef23456789abcdef01234567"
  }
}

Previous EndpointGenerate Mashup Music Next EndpointUpload And Cover Audio

Ready to integrate Replace Music Section?

Create your account, obtain your API key, and begin regenerating song sections seamlessly.

Generate Secret Key