Callbacks & WebhooksFree Webhook (0 Credits)Bearer Token AuthVoice Model Training

Custom Voice Generation Callback

Webhook callback payload specification sent to your server when custom voice cloning and acoustic model training completes. Delivers the unique voiceId identifier to unleash custom vocal timbre in full-band AI songs.

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:

  • Acoustic Model Training Complete (status: 'success'): Dispatched when vocal timbre characteristics and pitch ranges have been successfully synthesized into a persistent voice ID.
  • Voice Verification Failure (status: 'failed'): Dispatched if the submitted verification audio has high background noise, pitch distortion, or fails identity verification.
  • Processing Timeout / Server Retry: Dispatched if model generation exceeds max timeout thresholds, returning an explanatory errorCode and errorMessage.

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7f8b91c0e24147d3910c4fa891b29a42",
    "voiceId": "voice_c891a27e01b348d29f04",
    "status": "success",
    "errorCode": null,
    "errorMessage": ""
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerHTTP status code of the webhook delivery (200 = Success, 400/500 = Error).
msgstringStatus message indicating the overall outcome (e.g. "success").
data.taskIdstringUnique identifier of the voice generation task matching the taskId returned by POST /api/v1/createTask.
data.voiceIdstringPersistent unique custom voice identifier (e.g. "voice_c891a27e01b348d29f04"). Pass this ID in persona_id or voice_id for AI music singing.
data.statusstringStatus of custom voice training: "success" when the voice model is ready, or "failed" if validation fails.
data.errorCodestring | nullStandardized error code if voice generation failed (e.g. "NOISY_AUDIO", "PITCH_TOO_LOW", or null on success).
data.errorMessagestringDetailed human-readable explanation if voice model training encountered errors.

Receiver Implementation Example

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

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

app.post('/suno-voice-generate-callback', (req, res) => {
  const { code, msg, data } = req.body;

  console.log('Received Suno Voice generation callback:', {
    taskId: data?.taskId,
    voiceId: data?.voiceId,
    status: data?.status,
    message: msg
  });

  if (code === 200 && data?.status === 'success') {
    console.log('Voice generated successfully!');
    console.log(`Voice ID: ${data.voiceId}`);
    // Bind voiceId to user persona profile
  } else {
    console.error('Voice generation failed:', data?.errorMessage || msg);
  }

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

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

Acoustic Profile Persistence & Song Synthesis Usage

When your custom voice model completes training, the returned voiceId functions as a persistent vocal timbre identifier across the entire Suno AI platform:

Persistent Persona Linking

Save voiceId in your database associated with user profiles. You can reuse the same voice across hundreds of tracks without retraining.

Dynamic Genre Adaptation

The trained custom voice adapts dynamically to any musical tempo, key signature, vocal style, or language prompt specified in music generation requests.

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
Response Expectation
{"status": "received"}

Webhook Receiver Examples

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

interface VoiceGenerateCallbackPayload {
  code: number;
  msg: string;
  data: {
    taskId: string;
    voiceId?: string;
    status: 'success' | 'failed';
    errorCode?: string | null;
    errorMessage?: string;
  };
}

export async function POST(req: NextRequest) {
  try {
    const payload: VoiceGenerateCallbackPayload = await req.json();
    const { code, msg, data } = payload;

    console.log(`[Voice Generate Webhook] Task ${data?.taskId} -> Status: ${data?.status} (Code: ${code})`);

    if (code === 200 && data) {
      if (data.status === 'success' && data.voiceId) {
        console.log(`Custom voice created successfully! Voice ID: ${data.voiceId}`);
        // Save voiceId to user profile or database for persona music synthesis
      } else {
        console.error(`Voice training failed: ${data.errorMessage || msg} (Error Code: ${data.errorCode})`);
      }
    } else {
      console.error(`Webhook returned non-200 code: ${code} (${msg})`);
    }

    // Always acknowledge receipt immediately with HTTP 200
    return NextResponse.json({ code: 200, msg: 'success' });
  } catch (error) {
    console.error('Webhook processing error:', error);
    return NextResponse.json({ code: 500, msg: 'Internal server error' }, { status: 500 });
  }
}
Expected Server Acknowledgment(200 status)
{
  "code": 200,
  "msg": "success"
}
Previous EndpointUpload & Extend WebhookNext EndpointVoice Validation Phrase Webhook

Ready to integrate Custom Voice Generation Callbacks?

Create your free account, obtain your Secret Key, and receive real-time voice modeling updates with 5 free generation credits.

Generate Secret Key