Add Instrumental Callbacks
Real-time asynchronous webhook notifications delivered to your callBackUrl when full-band instrumental accompaniment generation beneath vocal tracks completes. Returns dual-track arrangements with mixed drums, bass, guitars, and orchestral layers.
Usage Guide & Overview
- Smart Accompaniment Synthesis: The model extracts pitch contours, phrasing rhythm, and emotion from an acapella audio track, generating full instrumentation (rhythm section, lead instruments, atmosphere) that conforms to the vocal key.
- Dual Arrangement Takes: Suno AI generates 2 distinct musical arrangement takes per task (e.g. different instrument choices, chord variations, or groove dynamics).
- Zero Credit Surcharge: Webhook callback delivery is completely free (0 credits) and incurs no extra fees.
- Vocal Stem Lineage: The callback returns
source_audio_urlreferencing the acapella vocal track supplied in the original request.
Delivery Conditions & Technical Constraints
Callback Stages (data.callbackType)
text: Key detection finished; arrangement structure and instrument roles mapped.first: First instrumental accompaniment variation rendered and available for preview.complete: Final state. Both full-band arrangements mixed with vocals, mastered, and hosted on CDN.error: Accompaniment synthesis failed due to noisy vocal source audio or engine timeout.
HTTP Transport & Timeout Specification
- HTTP Method: Requests are delivered via
POSTwithContent-Type: application/json. - 15-Second Response Window: Your server must acknowledge receipt with HTTP
200within 15 seconds. - Automated Retries: If your server fails to respond, returns 4xx/5xx, or times out, the dispatcher retries up to 3 times before abandoning.
- Public Accessibility: The
callBackUrlmust be accessible via public HTTPS.
Production Best Practices
- Immediate 200 Acknowledgment: Return HTTP 200 immediately before performing heavy downstream processing (downloading files, audio analysis, S3 archiving).
- Idempotent Handling: Use
task_id + callbackTypeas a compound unique key in your database. - Mixed Audio Storage: Download and archive the final MP3 files promptly onto your own persistent storage.
Troubleshooting & Verification Checklist
- Ensure your firewall and ingress load balancer permit incoming POST requests on your callback URL.
- For local development and testing, use reverse tunneling tools such as ngrok or Cloudflare Tunnel.
- Ensure your web application uses JSON body parsing middleware (e.g.
express.json()). - Confirm that your endpoint returns HTTP 200 rather than redirects.
Inbound HTTP Headers
| Header | Requirement | Description |
|---|---|---|
| Content-Type | required | application/json Inbound webhook payload encoded in UTF-8 JSON format |
| User-Agent | optional | Suno-Webhook-Dispatcher/1.0 User agent identifier sent by the webhook worker |
When Callbacks Are Sent
The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:
- Harmonic Structure Planned (callbackType: 'text'): Dispatched when chord detection on the vocal input finishes and instrumental section layout is planned.
- First Arrangement Ready (callbackType: 'first'): Dispatched when the first instrumental accompaniment variation is rendered and available for streaming.
- All Accompaniments Complete (callbackType: 'complete'): Dispatched when both full-band instrumental arrangements have been generated, mixed under the vocal stem, and mastered.
- Task Failure (callbackType: 'error'): Dispatched if the prompt violates safety filters or the acapella audio cannot be parsed for key and tempo.
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/instrumental_arrangement1.mp3",
"stream_audio_url": "https://example.cn/stream/instrumental_arrangement1",
"image_url": "https://example.cn/images/instrumental_cover1.jpeg",
"prompt": "Orchestral rock accompaniment, rich cello harmonies, acoustic drum kit, grand piano riffs",
"model_name": "chirp-v4-5",
"title": "Acapella Journey (Orchestral Rock Mix)",
"tags": "orchestral rock, driving drums, rich strings, piano accompaniment",
"createTime": 1786343609818,
"duration": 210.35,
"source_audio_url": "https://example.cn/music/original_acapella.mp3",
"source_image_url": "https://example.cn/images/acapella_cover.jpeg",
"source_stream_audio_url": "https://example.cn/stream/acapella_stream"
},
{
"id": "e231a482-9b11-4cb3-a9d2-5a218cadc7dd",
"audio_url": "https://example.cn/music/instrumental_arrangement2.mp3",
"stream_audio_url": "https://example.cn/stream/instrumental_arrangement2",
"image_url": "https://example.cn/images/instrumental_cover2.jpeg",
"prompt": "Electronic synthpop arrangement, deep sub-bass, 808 beats, shimmering arpeggios",
"model_name": "chirp-v4-5",
"title": "Acapella Journey (Synthpop Edition)",
"tags": "electronic synthpop, melodic synths, punchy bass, modern groove",
"createTime": 1786343609818,
"duration": 210.35,
"source_audio_url": "https://example.cn/music/original_acapella.mp3",
"source_image_url": "https://example.cn/images/acapella_cover.jpeg",
"source_stream_audio_url": "https://example.cn/stream/acapella_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 instrumental generation outcome (e.g. "All generated successfully."). |
data.callbackType | string | Lifecycle stage identifier: "text" (harmonic structure planned), "first" (take 1 ready), "complete" (all takes ready), or "error" (failed). |
data.task_id | string | Unique task identifier, identical to the taskId returned when submitting the task to POST /api/v1/createTask. |
data.data | array | Array containing generated instrumental accompaniment audio records (typically 2 distinct musical arrangements). |
data.data[].id | string | Unique UUID for the instrumental arrangement variation record. |
data.data[].audio_url | string | Direct download URL for the final mixed audio track (instrumental accompaniment + acapella vocals). |
data.data[].stream_audio_url | string | Streaming audio URL (HLS / m3u8 format) for real-time web playback. |
data.data[].image_url | string | Album artwork cover image URL created for the arranged track. |
data.data[].prompt | string | Style descriptors, instrument selections, or arrangement prompts supplied. |
data.data[].model_name | string | Underlying AI audio synthesis model used (e.g. "chirp-v4-5", "chirp-v4", "V6"). |
data.data[].title | string | Song title of the arranged track. |
data.data[].tags | string | Genre, tempo, instrument types, and arrangement descriptors. |
data.data[].createTime | integer | Unix millisecond timestamp when the track was synthesized. |
data.data[].duration | number | Total duration of the final mixed audio track in seconds. |
data.data[].source_audio_url | string | Direct audio URL of the input acapella vocal track. |
data.data[].source_image_url | string | Cover artwork image URL of the source vocal track. |
data.data[].source_stream_audio_url | string | Streaming audio URL of the source vocal track. |
Receiver Implementation Example
const express = require('express');
const app = express();
app.use(express.json({ limit: '10mb' }));
app.post('/suno-instrumental-callback', (req, res) => {
const { code, msg, data } = req.body;
console.log('Received Suno instrumental arrangement 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}] Harmonic progression and instruments planned:`, tracks);
break;
case 'first':
console.log(`[${task_id}] First instrumental variation ready:`, tracks?.[0]?.audio_url);
break;
case 'complete':
console.log(`[${task_id}] Both instrumental arrangements rendered successfully!`);
tracks?.forEach((track, index) => {
console.log(`Arrangement #${index + 1}: ${track.title} (${track.duration}s)`);
console.log(`- Mixed Track URL: ${track.audio_url}`);
console.log(`- Vocal Stem Source: ${track.source_audio_url}`);
});
break;
case 'error':
console.error(`[${task_id}] Instrumental generation 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 instrumental 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.
// app/api/webhook/suno-instrumental/route.ts
import { NextRequest, NextResponse } from 'next/server';
interface InstrumentalTrackItem {
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 InstrumentalCallbackPayload {
code: number;
msg: string;
data: {
callbackType: 'text' | 'first' | 'complete' | 'error';
task_id: string;
data?: InstrumentalTrackItem[];
};
}
export async function POST(req: NextRequest) {
try {
const payload: InstrumentalCallbackPayload = await req.json();
const { code, msg, data } = payload;
console.log(`[Instrumental Webhook] Task ${data?.task_id} -> Stage: ${data?.callbackType} (Code: ${code})`);
if (code === 200 && data) {
if (data.callbackType === 'complete') {
console.log(`Instrumental arrangement tracks ready: ${data.data?.length || 0}`);
for (const track of data.data || []) {
console.log(`Track: "${track.title}" (${track.duration}s)`);
console.log(`- Mixed Audio URL: ${track.audio_url}`);
console.log(`- Source Vocal Stem: ${track.source_audio_url}`);
}
} else if (data.callbackType === 'first') {
console.log(`[First Arrangement Take Ready] Stream: ${data.data?.[0]?.stream_audio_url}`);
} else if (data.callbackType === 'text') {
console.log('[Text Ready] Harmonic progression and instrument layout planned');
}
} else {
console.error(`Instrumental arrangement 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 Add Instrumental Callbacks?
Create your free account, obtain your Secret Key, and receive real-time accompaniment updates with 5 free generation credits.