Callbacks & WebhooksFree Webhook (0 Credits)Bearer Token AuthStructured Lyrics

Lyrics Generation Callbacks

Webhook callback payload specification sent to your server when a structured song lyrics generation task completes. Delivers metrically structured verses, catchy choruses, bridges, and suggested song titles.

WEBHOOKWebhook Callback (Your Server)
Test in Playground

When Callbacks Are Sent

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

  • Lyrics Composition Complete (callbackType: 'complete'): Dispatched once structured verses, choruses, bridges, and suggested titles are written and metrically balanced.
  • Moderation Failure / Error (callbackType: 'error'): Dispatched if the topic prompt violates copyright rules or content safety guidelines.

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "3b66882fde0a5d398bd269cab6d9542b",
    "data": [
      {
        "title": "Starry Night Dreams",
        "text": "[Verse 1]\nMoonlight spreads across the windowsill\nStars dance, never standing still\nNight breeze weaves dreams with gentle skill\nLeaving all worries on the hill\n\n[Chorus]\nIn starry dreams we find tomorrow\nBreak free from ordinary sorrow\nAll our dreams will bloom and follow\nDon't fear the path, don't fear tomorrow",
        "status": "complete",
        "error_message": ""
      },
      {
        "title": "Main Street Summer",
        "text": "[Verse 1]\nGolden sunshine on the pavement warm\nSummer breezes after the afternoon storm\nRadio playing our favorite song\nSinging out loud where we belong\n\n[Chorus]\nOh this summer feeling never fades\nDancing through the sunlit masquerades",
        "status": "complete",
        "error_message": ""
      }
    ]
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerHTTP status code of task processing (200 = Success, 400/500 = Error).
msgstringStatus message indicating outcome (e.g. "All generated successfully.").
data.callbackTypestringStatus indicator: "complete" when lyrics generation succeeded, or "error" on failure.
data.task_idstringUnique identifier matching the taskId returned by POST /api/v1/createTask.
data.dataarrayArray of distinct generated lyrics proposals (typically 2 creative variations).
data.data[].titlestringGenerated song title suggested for this lyrics variation.
data.data[].textstringFull song lyrics structured with standard bracketed musical tags ([Verse], [Chorus], [Bridge], [Outro]).
data.data[].statusstringGeneration state of this specific lyric proposal ("complete" or "failed").
data.data[].error_messagestringError details if this lyric proposal failed; empty string on success.

Receiver Implementation Example

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

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

app.post('/suno-lyrics-callback', (req, res) => {
  const { code, msg, data } = req.body;
  const taskId = data?.task_id;
  const lyricsList = data?.data || [];

  console.log('Received lyrics callback:', {
    taskId,
    status: code,
    message: msg
  });

  if (code === 200 && data) {
    lyricsList.forEach((song, idx) => {
      console.log(`Option #${idx + 1}: ${song.title}`);
      console.log(song.text);
    });
  } else {
    console.error('Lyrics generation failed:', msg);
  }

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

app.listen(3000, () => {
  console.log('Lyrics callback server 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.

Bracketed Tags & Metric Rhyme Structure

When requesting lyrics via POST /api/v1/createTask (taskType: "generate_lyrics"), the model formats output with industry-standard musical structure tags:

Structural Tags

Includes [Verse], [Chorus], [Bridge], and [Outro] tags, ready to feed directly into Suno Music Generation prompts.

Dual Creative Variations

Returns two alternative lyrical perspectives with different rhythm meters and title proposals for selection.

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
Format Encoding
UTF-8 multi-language lyrics support

Webhook Receiver Examples

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

interface LyricsItem {
  title: string;
  text: string;
  status: 'complete' | 'failed';
  error_message?: string;
}

interface LyricsCallbackPayload {
  code: number;
  msg: string;
  data: {
    callbackType: 'complete' | 'error';
    task_id: string;
    data?: LyricsItem[];
  };
}

export async function POST(req: NextRequest) {
  try {
    const payload: LyricsCallbackPayload = await req.json();
    const { code, msg, data } = payload;
    const taskId = data?.task_id;
    const lyricsList = data?.data || [];

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

    if (code === 200 && data) {
      console.log(`Generated ${lyricsList.length} lyric options:`);
      lyricsList.forEach((song, i) => {
        if (song.status === 'complete') {
          console.log(`Option #${i + 1}: "${song.title}"`);
          console.log(song.text.slice(0, 100) + '...');
        } else {
          console.error(`Option #${i + 1} failed: ${song.error_message}`);
        }
      });
      // Store lyrics in database or feed into music generation API
    } else {
      console.error(`Lyrics generation 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"
}
Previous EndpointConvert to WAV WebhookNext EndpointGenerate MIDI Webhook

Ready to integrate Lyrics Generation Callbacks?

Create your free account, obtain your Secret Key, and receive structured lyrics webhooks with 5 free generation credits.

Generate Secret Key