Callbacks & WebhooksFree Webhook (0 Credits)Bearer Token AuthIn-Painting Delivery

Replace Section Callbacks

Webhook callback payload specification sent to your server when an audio section replacement (musical in-painting) task completes. Returns dual-track final mixed audio with the specified timestamp interval regenerated and seamlessly cross-faded into your original song.

WEBHOOKWebhook Callback (Your Server)

When Callbacks Are Sent

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

  • Text & Lyric Alignment (callbackType: 'text'): Dispatched once replacement prompt verses and structural cues are harmonized with the source audio context.
  • First Replaced Variation Ready (callbackType: 'first'): Dispatched when the first seamless in-painted track variation is rendered and available for streaming.
  • All Variations Complete (callbackType: 'complete'): Dispatched when both audio variations with smoothly cross-faded replacement segments are finalized and hosted.
  • Task Failure (callbackType: 'error'): Dispatched if the replacement interval is out of bounds, audio cannot be retrieved, or content moderation triggers a block.

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac9a8109bf4a6385cf71e3b6999f72",
    "data": [
      {
        "id": "e231a481-9b11-4cb3-a9d2-5a218cadc7dc",
        "audio_url": "https://example.cn/music/replaced_section_var1.mp3",
        "stream_audio_url": "https://example.cn/stream/replaced_section_var1",
        "image_url": "https://example.cn/images/replaced_cover1.jpeg",
        "prompt": "[Verse 2]\nElectric dreams ignite the silent street\nUnder neon glows our hearts sync to the beat",
        "model_name": "chirp-v4-5",
        "title": "Neon Horizon (Chorus Replaced)",
        "tags": "synthwave, energetic lead guitar, driving bassline",
        "createTime": 1786343609818,
        "duration": 214.3,
        "source_audio_url": "https://example.cn/music/original_unreplaced_song.mp3",
        "source_image_url": "https://example.cn/images/original_cover.jpeg",
        "source_stream_audio_url": "https://example.cn/stream/original_stream"
      },
      {
        "id": "e231a482-9b11-4cb3-a9d2-5a218cadc7dd",
        "audio_url": "https://example.cn/music/replaced_section_var2.mp3",
        "stream_audio_url": "https://example.cn/stream/replaced_section_var2",
        "image_url": "https://example.cn/images/replaced_cover2.jpeg",
        "prompt": "[Verse 2]\nElectric dreams ignite the silent street\nUnder neon glows our hearts sync to the beat",
        "model_name": "chirp-v4-5",
        "title": "Neon Horizon (Alt Spliced Solo)",
        "tags": "synthwave, acoustic breakdown, emotional vocal lead",
        "createTime": 1786343609818,
        "duration": 214.3,
        "source_audio_url": "https://example.cn/music/original_unreplaced_song.mp3",
        "source_image_url": "https://example.cn/images/original_cover.jpeg",
        "source_stream_audio_url": "https://example.cn/stream/original_stream"
      }
    ]
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerStatus code of task processing. 200 indicates success; 400 or 500 indicates a failure.
msgstringDescriptive status message explaining the replacement outcome (e.g. "All generated successfully.").
data.callbackTypestringLifecycle stage identifier: "text" (verses planned), "first" (variation 1 spliced and ready), "complete" (all variations ready), or "error" (failed).
data.task_idstringUnique task identifier, identical to the taskId returned when submitting the section replacement task to POST /api/v1/createTask.
data.dataarrayArray containing generated audio variations with the target segment seamlessly regenerated and re-spliced (typically 2 variations).
data.data[].idstringUnique UUID for the re-spliced audio variation record.
data.data[].audio_urlstringHigh-quality master MP3 download URL of the complete song with the target section seamlessly re-spliced.
data.data[].stream_audio_urlstringLow-latency streaming audio URL for instantaneous in-browser or in-app preview playback.
data.data[].image_urlstringHigh-resolution square cover artwork URL generated for this audio variation.
data.data[].promptstringThe replacement lyric snippet or structural musical prompt substituted into the specified timestamp interval.
data.data[].model_namestringAI generation engine used to synthesize and splice the section (e.g. "chirp-v4-5").
data.data[].titlestringTitle assigned to the modified audio variation.
data.data[].tagsstringMusical genre tags, tempo, instrumentation, and vocal descriptors applied to the replaced segment.
data.data[].createTimeintegerUnix millisecond timestamp recording when the spliced variation was generated.
data.data[].durationnumberTotal duration of the final spliced audio track in seconds.
data.data[].source_audio_urlstringOriginal unedited source audio URL provided prior to section replacement, allowing delta comparison.
data.data[].source_image_urlstringOriginal album cover artwork URL associated with the source song.
data.data[].source_stream_audio_urlstringStreaming URL of the original song prior to in-painting modification.

Receiver Implementation Example

Webhook Receiver
const express = require('express');
const app = express();

app.use(express.json({ limit: '10mb' }));

app.post('/suno-replace-section-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received Suno replace-section callback:', {
    taskId: data?.task_id,
    callbackType: data?.callbackType,
    status: code,
    message: msg
  });

  if (code === 200 && data) {
    const { callbackType, task_id, data: tracks } = data;

    switch (callbackType) {
      case 'text':
        console.log(`[${task_id}] Replacement verses processed:`, tracks);
        break;

      case 'first':
        console.log(`[${task_id}] First spliced audio variation ready:`, tracks?.[0]?.audio_url);
        break;

      case 'complete':
        console.log(`[${task_id}] Both spliced audio variations generated successfully!`);
        tracks?.forEach((track, index) => {
          console.log(`Variation #${index + 1}: ${track.title} (${track.duration}s)`);
          console.log(`- Spliced MP3 URL: ${track.audio_url}`);
          console.log(`- Stream URL: ${track.stream_audio_url}`);
          console.log(`- Source Audio: ${track.source_audio_url}`);
        });
        break;

      case 'error':
        console.error(`[${task_id}] Section replacement failed:`, msg);
        break;
    }
  } else {
    console.error('Task failed or returned non-200 code:', code, msg);
  }

  // Always return HTTP 200 within 15 seconds to acknowledge receipt
  return res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Suno replace-section webhook listener running on port 3000');
});

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.

Section In-Painting Workflow & Seamless Splicing

When you submit a section replacement request to POST /api/v1/createTask with taskType: "replace_section", the AI isolates the target time window (e.g. from second 45 to second 75), synthesizes new musical accompaniment or vocal lines based on your updated prompt, and executes acoustic phase matching at boundary splice points:

Acoustic Context Match

The generation engine analyzes the preceding and following musical bars (key, BPM, instrumentation, reverberation) to prevent jarring timbre transitions.

Micro-Crossfade Splicing

The replaced segment is rendered directly into the complete track with micro-crossfades applied at zero-crossing points to eliminate audio clicks and pops.

Webhook Delivery & Reliability Protocol

Delivery Method
POST (application/json)
Client Response Timeout
15 seconds timeout window
Retry Mechanism
Up to 3 retries on non-200 responses
Asset Retention
CDN signed links valid for 24 hours

Webhook Receiver Examples

Request Example
// app/api/webhook/suno-replace-section/route.ts
import { NextRequest, NextResponse } from 'next/server';

interface ReplacedTrackItem {
  id: string;
  audio_url: string;
  stream_audio_url: string;
  image_url: string;
  prompt: string;
  model_name: string;
  title: string;
  tags: string;
  createTime: number;
  duration: number;
  source_audio_url?: string;
  source_image_url?: string;
  source_stream_audio_url?: string;
}

interface ReplaceSectionCallbackPayload {
  code: number;
  msg: string;
  data: {
    callbackType: 'text' | 'first' | 'complete' | 'error';
    task_id: string;
    data?: ReplacedTrackItem[];
  };
}

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

    console.log(`[Replace Section Webhook] Task ${data?.task_id} -> Stage: ${data?.callbackType} (Code: ${code})`);

    if (code === 200 && data) {
      if (data.callbackType === 'complete') {
        console.log(`Section replacement completed! Variations delivered: ${data.data?.length || 0}`);
        for (const track of data.data || []) {
          console.log(`Track: "${track.title}" (Duration: ${track.duration}s)`);
          console.log(`- Spliced MP3 URL: ${track.audio_url}`);
          console.log(`- Preceding Source Audio: ${track.source_audio_url}`);
        }
      } else if (data.callbackType === 'first') {
        console.log(`[First Spliced Variation Ready] Stream: ${data.data?.[0]?.stream_audio_url}`);
      } else if (data.callbackType === 'text') {
        console.log('[Text Ready] In-painting lyrical segment parsed and harmonized');
      }
    } else {
      console.error(`Section replacement failed: ${msg}`);
    }

    // Always acknowledge receipt immediately with HTTP 200
    return NextResponse.json({ code: 200, msg: 'success' });
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json({ code: 500, msg: 'Internal server error' }, { status: 500 });
  }
}
Expected Server Acknowledgment(200 status)
{
  "code": 200,
  "msg": "success"
}

Ready to integrate Replace Section Callbacks?

Create your free account, obtain your Secret Key, and receive real-time musical in-painting notifications with 5 free generation credits.

Generate Secret Key