Callbacks & WebhooksFree Webhook (0 Credits)Dual Cover Art DeliveryAsynchronous HTTP POST

Cover Suno Callbacks

Real-time asynchronous webhook callback delivered to your callBackUrl when an album cover art generation task (cover_suno) finishes. Delivers 2 distinct high-resolution album cover artwork image URLs tailored to your music.

WEBHOOKYour Callback Endpoint (Client HTTPS URL)
Test in Playground

Usage Guide & Overview

  • Asynchronous Cover Art Pipeline: AI album artwork rendering takes 10–30 seconds. Submitting a callBackUrl when invoking POST /api/v1/createTask with model: "ai-music-api/cover-generate" ensures you receive completion data automatically without holding connections open.
  • Dual Visual Variations: The system synthesizes 2 different artistic style cover images simultaneously for each music track, giving end users visual choices.
  • Zero Credit Surcharge: Webhook callback delivery is completely free (0 credits) and incurs no extra fees.
  • Temporary Asset Retention: Image URLs delivered in the callback are stored on temporary CDN storage. You should download and persist them to your permanent cloud storage (S3, Cloudflare R2, OSS) upon receipt.

Delivery Conditions & Technical Constraints

Callback Trigger Conditions

  • 200 Success : Both album cover art variations generated successfully and hosted on CDN.
  • 501 Generation Failed : Rendering pipeline encountered an error or prompt flagged by moderation.
  • 400 / 500 / 531 : Invalid request parameters, server exception, or credit refund event.

HTTP Transport & Timeout Specification

  • HTTP Method: Requests are delivered via POST with Content-Type: application/json.
  • 15-Second Timeout: Your callback server must acknowledge receipt with HTTP 200 within 15 seconds.
  • Retry Policy: If your server fails to respond, returns 4xx/5xx, or times out, the system will retry up to 3 times before abandoning delivery.
  • Public Accessibility: The callBackUrl must be accessible via public HTTPS. Localhost or private IP addresses will fail to receive callbacks.

Production Best Practices

  • Immediate 200 Acknowledgment: Return HTTP 200 immediately before performing file downloads, resizing, or upload operations.
  • Idempotent Handling: Use data.taskId as a unique key in your database to prevent duplicate processing on retries.
  • Prompt Image Archiving: Image links have limited validity; download and store PNG files permanently in your asset pipeline.
  • Download Error Retries: Wrap the image download process in exponential retry logic to handle transient network hiccups.

Troubleshooting & Verification Checklist

  • Verify that your firewall and ingress load balancer permit incoming POST requests on your callback URL.
  • For local development, use tunneling tools like ngrok or Cloudflare Tunnel to expose your local port publicly.
  • Ensure your web application uses JSON body parsing middleware (e.g. express.json()).
  • Confirm that your endpoint returns HTTP 200 rather than 301/302 redirects, which abort the webhook delivery.

Inbound HTTP Headers

HeaderRequirementDescription
Content-Typerequired

application/json

Inbound webhook payload encoded in UTF-8 JSON format

User-Agentoptional

Suno-Webhook-Dispatcher/1.0

User agent identifier sent by the webhook worker

When Callbacks Are Sent

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

  • Task Complete (code: 200): Dispatched when high-resolution album cover art generation completes, returning 2 distinct visual style variants.
  • Task Failed (code: 501): Dispatched if prompt evaluation fails, visual moderation flags content, or rendering encounters an error.
  • Processing Exception (code: 400, 500, 531): Dispatched if task parameter validation fails or credit refund occurs.

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "21aee3c3c2a01fa5e030b3799fa4dd56",
    "images": [
      "https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png",
      "https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
    ]
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerStatus code of task processing. 200 = Success, 400 = Invalid parameter, 500 = Server error, 501 = Cover generation failed, 531 = Task refunded.
msgstringDetailed status description message ("success" or specific failure explanation).
data.taskIdstringUnique identifier of the cover generation task, matching the taskId returned from POST /api/v1/createTask.
data.imagesarrayArray of generated high-resolution cover image URLs (typically 2 distinct artistic style options; recommend downloading promptly).

Receiver Implementation Example

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

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

app.post('/suno-cover-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received cover generation callback:', {
    taskId: data?.taskId,
    status: code,
    message: msg
  });

  if (code === 200) {
    const images = data?.images || [];
    console.log(`Generated ${images.length} cover art images:`);
    images.forEach((imageUrl, index) => {
      console.log(`Cover #${index + 1}: ${imageUrl}`);
    });

    // Important: Image URLs are temporary. Download and archive promptly.
  } else {
    console.error(`Cover generation failed (status ${code}): ${msg}`);
  }

  // Return HTTP 200 status code within 15 seconds to confirm receipt
  res.status(200).json({ status: 'received' });
});

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

Webhook Implementation
// app/api/webhook/suno-cover/route.ts
import { NextRequest, NextResponse } from 'next/server';

interface CoverCallbackPayload {
  code: number;
  msg: string;
  data?: {
    taskId: string;
    images?: string[];
  };
}

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

    console.log(`[Cover Webhook] Task ${data?.taskId} -> Status: ${code} (${msg})`);

    if (code === 200 && data) {
      const { taskId, images } = data;
      console.log(`Cover images generated for task ${taskId}:`, images);

      // Download and persist images to your persistent storage (S3 / Cloud Storage)
      for (let i = 0; i < (images?.length || 0); i++) {
        console.log(`Image #${i + 1}: ${images?.[i]}`);
      }
    } else {
      console.error(`Cover art generation failed (code ${code}): ${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 });
  }
}
Your Server's Expected Response (HTTP 200 OK)
Response Body(200 status)
{
  "code": 200,
  "msg": "success"
}
Previous EndpointGenerate Music WebhookNext EndpointExtend Music Webhook

Ready to integrate Cover Art Generation Callbacks?

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

Generate Secret Key