Music Cover Generation Callbacks

When music cover generation is complete, the system will call this callback to notify results.

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

Webhook Security

To ensure the authenticity and integrity of callback requests, we strongly recommend implementing webhook signature verification. See our Webhook Verification Guide for detailed implementation steps.

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:

Success Callback

Failure Callback

{
  "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 Code	Description
200	Success - Request processed successfully
400	Validation error - Request parameters invalid
408	Rate limited - Timeout
500	Server error - Unexpected error occurred while processing request
501	Cover generation failed
531	Server 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:

Node.js

Python

Java

PHP

Best Practices

Callback URL Configuration Recommendations

Use HTTPS: Ensure callback URL uses HTTPS protocol for data transmission security

Verify Source: Verify the legitimacy of request sources in callback processing

Idempotent Processing: The same taskId may receive multiple callbacks, ensure processing logic is idempotent

Quick Response: Callback processing should return 200 status code quickly to avoid timeout

Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback response

Image Management: Download and save images promptly, noting URL validity period

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:

Network Connection Issues

Confirm callback URL is accessible from the public internet

Check firewall settings to ensure inbound requests are not blocked

Verify domain name resolution is correct

Server Response Issues

Ensure server returns HTTP 200 status code within 15 seconds

Check server logs for error messages

Verify interface path and HTTP method are correct

Content Format Issues

Confirm received POST request body is in JSON format

Check if Content-Type is application/json

Verify JSON parsing is correct

Image Processing Issues

Confirm image URLs are accessible

Check image download permissions and network connection

Verify file save path and permissions

Note image URL validity period limitations

Music Cover Generation Callbacks

Callback Mechanism Overview#

Callback Timing#

Callback Method#

Callback Request Format#

Status Code Description#

code (integer, required)#

msg (string, required)#

data.taskId (string, required)#

data.images (array)#

Callback Reception Examples#

Best Practices#

Troubleshooting#

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

code (integer, required)

msg (string, required)

data.taskId (string, required)

data.images (array)

Callback Reception Examples

Best Practices

Troubleshooting