Callbacks & WebhooksFree Webhook (0 Credits)Bearer Token AuthUploaded Audio Cover

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.

WEBHOOKWebhook Callback (Your Server)

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

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/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

FieldTypeDescription
codeintegerStatus code of task processing. 200 indicates success; 400 or 500 indicates a failure.
msgstringDescriptive status message explaining the outcome (e.g. "All generated successfully.").
data.callbackTypestringLifecycle stage identifier: "text" (acoustic analysis ready), "first" (variation 1 ready), "complete" (all cover tracks ready), or "error" (failed).
data.task_idstringUnique task identifier, identical to the taskId returned when submitting the upload & cover request to POST /api/v1/createTask.
data.dataarrayArray containing generated AI cover audio variations (typically 2 distinct arrangement interpretations).
data.data[].idstringUnique UUID for the generated AI cover variation record.
data.data[].audio_urlstringHigh-quality master MP3 download URL of the re-arranged AI cover track.
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 cover audio variation.
data.data[].promptstringLyrics, stylistic guidance, or structural prompts applied to re-imagine the uploaded melody.
data.data[].model_namestringAI generation engine used to compose and render the cover version (e.g. "chirp-v4-5").
data.data[].titlestringTitle assigned to the re-imagined cover audio variation.
data.data[].tagsstringMusical genre tags, instrumentation, vocal descriptors, and production aesthetics used in the cover version.
data.data[].createTimeintegerUnix millisecond timestamp recording when the cover variation was created.
data.data[].durationnumberTotal duration of the final cover audio track in seconds.
data.data[].source_audio_urlstringURL of the original uploaded audio file used as the melodic and harmonic source for this cover.
data.data[].source_image_urlstringCover image or placeholder image associated with the initial uploaded sound file.
data.data[].source_stream_audio_urlstringStreaming URL of the original uploaded sound recording.

Receiver Implementation Example

Webhook Receiver
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:

Harmonic & Melodic Retention

The audio encoder captures pitch contours, chord cadences, and rhythm grooves from your uploaded file, preventing generic random generation.

Original Source Traceability

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

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-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 });
  }
}
Expected Server Acknowledgment(200 status)
{
  "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.

Generate Secret Key