Upload & Cover Audio Callbacks
Webhook callback payload specification sent to your server when an audio cover task based on user-uploaded audio completes. Delivers dual-track complete song variations that re-harmonize and re-arrange your uploaded melody into your target genre and vocal style.
When Callbacks Are Sent
The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:
- Acoustic Audio Analysis (callbackType: 'text'): Dispatched when the uploaded audio file's pitch, key, tempo, and chord sequences have been transcribed and style prompt planned.
- First Cover Variation Ready (callbackType: 'first'): Dispatched when the first AI cover version is fully arranged, rendered, and available for streaming.
- All Cover Tracks Complete (callbackType: 'complete'): Dispatched when both AI cover arrangement variations have been synthesized, mixed, and hosted.
- Task Failure (callbackType: 'error'): Dispatched if the uploaded audio file is corrupt, silent, exceeds size limits, or violates content safety policies.
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/ai_cover_acoustic_version.mp3",
"stream_audio_url": "https://example.cn/stream/ai_cover_acoustic_version",
"image_url": "https://example.cn/images/cover_artwork_1.jpeg",
"prompt": "[Verse]\nMelody reborn with acoustic warmth\nStrings vibrating through the quiet night",
"model_name": "chirp-v4-5",
"title": "Acoustic Whispers (AI Cover)",
"tags": "acoustic folk, fingerpicking guitar, soft male vocal, organic ambience",
"createTime": 1786343609818,
"duration": 218.4,
"source_audio_url": "https://example.cn/uploads/user_voice_note_original.mp3",
"source_image_url": "https://example.cn/images/default_audio_cover.jpeg",
"source_stream_audio_url": "https://example.cn/stream/user_voice_note_stream"
},
{
"id": "e231a482-9b11-4cb3-a9d2-5a218cadc7dd",
"audio_url": "https://example.cn/music/ai_cover_synthpop_version.mp3",
"stream_audio_url": "https://example.cn/stream/ai_cover_synthpop_version",
"image_url": "https://example.cn/images/cover_artwork_2.jpeg",
"prompt": "[Verse]\nMelody reborn with acoustic warmth\nStrings vibrating through the quiet night",
"model_name": "chirp-v4-5",
"title": "Electric Glow (AI Cover - Synthpop)",
"tags": "80s synthpop, driving synthesizer, energetic rhythm, polished lead vocal",
"createTime": 1786343609818,
"duration": 224.15,
"source_audio_url": "https://example.cn/uploads/user_voice_note_original.mp3",
"source_image_url": "https://example.cn/images/default_audio_cover.jpeg",
"source_stream_audio_url": "https://example.cn/stream/user_voice_note_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 outcome (e.g. "All generated successfully."). |
data.callbackType | string | Lifecycle stage identifier: "text" (acoustic analysis ready), "first" (variation 1 ready), "complete" (all cover tracks ready), or "error" (failed). |
data.task_id | string | Unique task identifier, identical to the taskId returned when submitting the upload & cover request to POST /api/v1/createTask. |
data.data | array | Array containing generated AI cover audio variations (typically 2 distinct arrangement interpretations). |
data.data[].id | string | Unique UUID for the generated AI cover variation record. |
data.data[].audio_url | string | High-quality master MP3 download URL of the re-arranged AI cover track. |
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 cover audio variation. |
data.data[].prompt | string | Lyrics, stylistic guidance, or structural prompts applied to re-imagine the uploaded melody. |
data.data[].model_name | string | AI generation engine used to compose and render the cover version (e.g. "chirp-v4-5"). |
data.data[].title | string | Title assigned to the re-imagined cover audio variation. |
data.data[].tags | string | Musical genre tags, instrumentation, vocal descriptors, and production aesthetics used in the cover version. |
data.data[].createTime | integer | Unix millisecond timestamp recording when the cover variation was created. |
data.data[].duration | number | Total duration of the final cover audio track in seconds. |
data.data[].source_audio_url | string | URL of the original uploaded audio file used as the melodic and harmonic source for this cover. |
data.data[].source_image_url | string | Cover image or placeholder image associated with the initial uploaded sound file. |
data.data[].source_stream_audio_url | string | Streaming URL of the original uploaded sound recording. |
Receiver Implementation Example
const express = require('express');
const app = express();
app.use(express.json({ limit: '10mb' }));
app.post('/suno-upload-cover-callback', (req, res) => {
const { code, msg, data } = req.body;
console.log('Received Suno upload & cover 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}] Uploaded audio analyzed, style arranged:`, tracks);
break;
case 'first':
console.log(`[${task_id}] First cover variation ready:`, tracks?.[0]?.audio_url);
break;
case 'complete':
console.log(`[${task_id}] Both AI cover arrangements completed successfully!`);
tracks?.forEach((track, index) => {
console.log(`Cover #${index + 1}: ${track.title} (${track.duration}s)`);
console.log(`- Cover MP3: ${track.audio_url}`);
console.log(`- Stream URL: ${track.stream_audio_url}`);
console.log(`- Uploaded Source File: ${track.source_audio_url}`);
});
break;
case 'error':
console.error(`[${task_id}] Cover 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 upload & cover 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.
Melodic Feature Extraction & Re-Arrangement Engine
When you submit a cover request with an uploaded sound recording to POST /api/v1/createTask (taskType: "upload_and_cover_audio"), the model decomposes the audio signal to maintain core musical identity while transforming style:
The audio encoder captures pitch contours, chord cadences, and rhythm grooves from your uploaded file, preventing generic random generation.
The webhook payload retains the unedited uploaded sound in source_audio_url, enabling side-by-side A/B comparison and playback.
Webhook Delivery & Reliability Protocol
Webhook Receiver Examples
// app/api/webhook/suno-upload-cover/route.ts
import { NextRequest, NextResponse } from 'next/server';
interface CoverTrackItem {
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 UploadCoverCallbackPayload {
code: number;
msg: string;
data: {
callbackType: 'text' | 'first' | 'complete' | 'error';
task_id: string;
data?: CoverTrackItem[];
};
}
export async function POST(req: NextRequest) {
try {
const payload: UploadCoverCallbackPayload = await req.json();
const { code, msg, data } = payload;
console.log(`[Upload & Cover Webhook] Task ${data?.task_id} -> Stage: ${data?.callbackType} (Code: ${code})`);
if (code === 200 && data) {
if (data.callbackType === 'complete') {
console.log(`Audio cover rendering completed! Variations ready: ${data.data?.length || 0}`);
for (const track of data.data || []) {
console.log(`Cover Track: "${track.title}" (${track.duration}s)`);
console.log(`- Master MP3: ${track.audio_url}`);
console.log(`- Uploaded Source Audio: ${track.source_audio_url}`);
}
} else if (data.callbackType === 'first') {
console.log(`[First Cover Variation Ready] Stream URL: ${data.data?.[0]?.stream_audio_url}`);
} else if (data.callbackType === 'text') {
console.log('[Text Ready] Audio acoustic analysis and style prompts mapped');
}
} else {
console.error(`Upload & Cover task 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 Upload & Cover Audio Callbacks?
Create your free account, obtain your Secret Key, and receive real-time audio cover notifications with 5 free generation credits.