When you submit a cover generation task to the Suno API, you can use the callBackUrl parameter to set the callback URL. When the task is complete, the system will automatically push results to your specified address.

​
Callback Mechanism Overview

The callback mechanism eliminates the need to poll the API for task status. The system will actively push task completion results to your server.

​
Callback Timing

The system will send callback notifications in the following situations:
  • Cover generation task completed successfully
  • Cover generation task failed
  • Error occurred during task processing

​
Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout Setting: 15 seconds

​
Callback Request Format

When the task is complete, the system will send a POST request to your callBackUrl: 
{
  "code": 200,
  "data": {
    "images": [
      "https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png",
      "https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
    ],
    "taskId": "21aee3c3c2a01fa5e030b3799fa4dd56"
  },
  "msg": "success"
}

​
Status Code Description

​
code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - Request processed successfully
400Validation error - Request parameters invalid
408Rate limited - Timeout
500Server error - Unexpected error occurred while processing request
501Cover generation failed
531Server error - Sorry, generation failed due to an issue. Your credits have been refunded. Please try again
​
msg
string
required
Status message providing more detailed status description
​
data.taskId
string
required
Task ID, consistent with the taskId returned when you submitted the task
​
data.images
array
Array of generated cover image URLs, returned on success. Usually contains 2 different style cover images

​
Callback Reception Examples

Here are example codes for receiving callbacks in common programming languages: 
const express = require('express');
const app = express();

app.use(express.json());

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) {
    // Task completed successfully
    console.log('Cover generation completed');
    const images = data.images;
    
    if (images && images.length > 0) {
      console.log('Generated cover images:');
      images.forEach((imageUrl, index) => {
        console.log(`Cover ${index + 1}: ${imageUrl}`);
      });
      
      // Process cover images
      // Can download images, save locally, update database, etc.
      downloadImages(images, data.taskId);
    }
    
  } else {
    // Task failed
    console.log('Cover generation failed:', msg);
    
    // Handle failure cases...
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

// Download images function
async function downloadImages(imageUrls, taskId) {
  const fs = require('fs');
  const path = require('path');
  const https = require('https');
  
  // Create directory
  const dir = `covers/${taskId}`;
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }
  
  for (let i = 0; i < imageUrls.length; i++) {
    const url = imageUrls[i];
    const filename = path.join(dir, `cover_${i + 1}.png`);
    
    try {
      await downloadFile(url, filename);
      console.log(`Cover saved: ${filename}`);
    } catch (error) {
      console.error(`Download failed: ${error.message}`);
    }
  }
}

function downloadFile(url, filename) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(filename);
    https.get(url, (response) => {
      response.pipe(file);
      file.on('finish', () => {
        file.close();
        resolve();
      });
    }).on('error', (err) => {
      fs.unlink(filename, () => {}); // Delete failed file
      reject(err);
    });
  });
}

app.listen(3000, () => {
  console.log('Callback server running on port 3000');
});

​
Best Practices

​
Callback URL Configuration Recommendations

  1. Use HTTPS: Ensure callback URL uses HTTPS protocol for data transmission security
  2. Verify Source: Verify the legitimacy of request sources in callback processing
  3. Idempotent Processing: The same taskId may receive multiple callbacks, ensure processing logic is idempotent
  4. Quick Response: Callback processing should return 200 status code quickly to avoid timeout
  5. Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback response
  6. Image Management: Download and save images promptly, noting URL validity period
  7. Error Retry: Implement retry mechanism for failed image downloads

​
Important Reminders

  • Callback URL must be a publicly accessible address
  • Server must respond within 15 seconds, otherwise it will be considered timeout
  • If 3 consecutive retries fail, the system will stop sending callbacks
  • Please ensure stability of callback processing logic to avoid callback failures due to exceptions
  • Cover image URLs may have validity periods, recommend downloading and saving promptly
  • Usually generates 2 different style cover images for selection
  • Note handling exceptions for failed image downloads

​
Troubleshooting

If you don’t receive callback notifications, please check the following:

​
Alternative Solutions

If you cannot use the callback mechanism, you can also use polling:

Poll Query Results

Use the Get Cover Details endpoint to periodically query task status. We recommend querying every 30 seconds.