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.
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
{
"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
| Field | Type | Description |
|---|---|---|
code | integer | Status code of task processing. 200 indicates success; 400 or 500 indicates a failure. |
msg | string | Descriptive status message explaining the replacement outcome (e.g. "All generated successfully."). |
data.callbackType | string | Lifecycle stage identifier: "text" (verses planned), "first" (variation 1 spliced and ready), "complete" (all variations ready), or "error" (failed). |
data.task_id | string | Unique task identifier, identical to the taskId returned when submitting the section replacement task to POST /api/v1/createTask. |
data.data | array | Array containing generated audio variations with the target segment seamlessly regenerated and re-spliced (typically 2 variations). |
data.data[].id | string | Unique UUID for the re-spliced audio variation record. |
data.data[].audio_url | string | High-quality master MP3 download URL of the complete song with the target section seamlessly re-spliced. |
data.data[].stream_audio_url | string | Low-latency streaming audio URL for instantaneous in-browser or in-app preview playback. |
data.data[].image_url | string | High-resolution square cover artwork URL generated for this audio variation. |
data.data[].prompt | string | The replacement lyric snippet or structural musical prompt substituted into the specified timestamp interval. |
data.data[].model_name | string | AI generation engine used to synthesize and splice the section (e.g. "chirp-v4-5"). |
data.data[].title | string | Title assigned to the modified audio variation. |
data.data[].tags | string | Musical genre tags, tempo, instrumentation, and vocal descriptors applied to the replaced segment. |
data.data[].createTime | integer | Unix millisecond timestamp recording when the spliced variation was generated. |
data.data[].duration | number | Total duration of the final spliced audio track in seconds. |
data.data[].source_audio_url | string | Original unedited source audio URL provided prior to section replacement, allowing delta comparison. |
data.data[].source_image_url | string | Original album cover artwork URL associated with the source song. |
data.data[].source_stream_audio_url | string | Streaming URL of the original song prior to in-painting modification. |
Receiver Implementation Example
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:
The generation engine analyzes the preceding and following musical bars (key, BPM, instrumentation, reverberation) to prevent jarring timbre transitions.
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
Webhook Receiver Examples
// 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 });
}
}{
"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.