Callbacks & WebhooksFree Webhook (0 Credits)Bearer Token Auth1080p MP4 Video

Music Video Generation Callbacks

Webhook callback payload specification sent to your server when an MP4 music video rendering task completes. Delivers high-definition 1080p H.264 video synchronized with your audio track and visual art.

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:

  • Video Rendering Complete (code: 200): Dispatched once motion visuals, audio track, and lyrics subtitle overlays are encoded into standard H.264/AAC MP4 format.
  • Rendering Failure (code: 400/500): Dispatched if source audio or artwork dimensions are invalid or rendering times out.

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "task_id": "task_id_5bbe7721119d45a2",
    "video_url": "https://example.cn/videos/suno_mv_847715e66259_1080p.mp4"
  }
}

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.task_idstringUnique identifier matching the taskId returned by POST /api/v1/createTask.
data.video_urlstringDirect download URL for the rendered 1080p MP4 music video (valid for 14 days).

Receiver Implementation Example

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

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

app.post('/suno-video-callback', (req, res) => {
  const { code, msg, data } = req.body;
  const taskId = data?.task_id;
  const videoUrl = data?.video_url;

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

  if (code === 200 && videoUrl) {
    console.log('Music video generation completed successfully!');
    console.log(`Video URL: ${videoUrl}`);
    console.log('Note: Video link remains valid for 14 days on CDN.');
    // Trigger download or social video publishing
  } else {
    console.error('Music video rendering failed:', msg);
  }

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

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

Video Encoding Specifications & Distribution

When requesting a video via POST /api/v1/createTask (taskType: "create_music_video"), the cloud rendering farm encodes visuals conforming to modern web standards:

Standard H.264 / AAC Encoding

Encoded in 1080p (1920x1080) at 30/60 fps with 320kbps AAC audio, fully compatible with YouTube, TikTok, Instagram Reels, and web video players.

14-Day CDN Retention Window

The video_url remains active for 14 days, providing generous time to transfer files to long-term storage or streaming CDNs.

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
File Size Allowance
MP4 files typically 50MB - 250MB

Webhook Receiver Examples

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

interface VideoCallbackPayload {
  code: number;
  msg: string;
  data: {
    task_id: string;
    video_url?: string;
  };
}

export async function POST(req: NextRequest) {
  try {
    const payload: VideoCallbackPayload = await req.json();
    const { code, msg, data } = payload;
    const taskId = data?.task_id;
    const videoUrl = data?.video_url;

    console.log(`[Music Video Webhook] Task ${taskId} -> Code: ${code}`);

    if (code === 200 && videoUrl) {
      console.log(`Music Video MP4 rendered successfully: ${videoUrl}`);
      console.log('CDN download link active (retention: 14 days)');
      // Offload video caching or social publishing to queue
    } else {
      console.error(`Music video rendering 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 EndpointGenerate MIDI WebhookNext EndpointWebhook Security Verification

Ready to integrate Music Video Generation Callbacks?

Create your free account, obtain your Secret Key, and receive rendered 1080p MP4 music video webhooks with 5 free generation credits.

Generate Secret Key