Lyrics Generation Callbacks

System will call this callback when lyrics generation is complete.

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

Callback Mechanism Overview

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

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:

Lyrics generation task completed successfully

Lyrics generation task failed

Errors occurred during task processing

Callback Method

HTTP Method: POST

Content Type: application/json

Timeout Setting: 15 seconds

Callback Request Format

When the task is completed, the system will send a POST request to your callBackUrl in the following format:

Success Callback

Failure Callback

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "3b66882fde0a5d398bd269cab6d9542b",
    "data": [
      {
        "error_message": "",
        "status": "complete",
        "text": "[Verse]\nMoonlight spreads across the windowsill\nStars dance, never standing still\nNight breeze weaves dreams with gentle skill\nLeaving all worries on the hill\n\n[Verse 2]\nLights reflect in your bright eyes\nLike meteors across the skies\nThe world stops in that moment's prize\nChasing future, no goodbyes\n\n[Chorus]\nIn starry dreams we find tomorrow\nBreak free from ordinary sorrow\nAll our dreams will bloom and follow\nDon't fear the path, don't fear tomorrow",
        "title": "Starry Night Dreams"
      }
    ]
  }
}

Status Code Description

code (integer, required)

Callback status code indicating task processing result:

Status Code	Description
200	Success - Request has been processed successfully
400	Please try rephrasing with more specific details or using a different approach
500	Internal Error - Please try again later

msg (string, required)

Status message providing detailed status description

data.callbackType (string, required)

Callback type, fixed as complete

data.task_id (string, required)

Task ID, consistent with the task_id returned when you submitted the task

data.data (array, required)

Generated lyrics list

data.data[].text (string)

Lyrics content, returns complete lyrics text on success

data.data[].title (string)

Lyrics title

data.data[].status (string, required)

Generation status:

complete - Generation successful

failed - Generation failed

data.data[].error_message (string)

Error message, valid when status is failed

Callback Reception Examples

Here are example codes for receiving callbacks in popular programming languages:

Node.js

Python

PHP

Best Practices

Callback URL Configuration Recommendations

Use HTTPS: Ensure your callback URL uses HTTPS protocol for secure data transmission

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

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

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

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

Status Checking: Check the status field of each lyrics item to distinguish between success and failure cases

Important Reminders

Callback URL must be a publicly accessible address

Server must respond within 15 seconds, otherwise it will be considered a timeout

If 3 consecutive retries fail, the system will stop sending callbacks

Please ensure the stability of callback processing logic to avoid callback failures due to exceptions

Pay attention to handling lyrics generation failure cases, check the error_message field for specific error information

Troubleshooting

If you do not receive callback notifications, please check the following:

Network Connection Issues

Confirm that the callback URL is accessible from the public network

Check firewall settings to ensure inbound requests are not blocked

Verify that domain name resolution is correct

Server Response Issues

Ensure the server returns HTTP 200 status code within 15 seconds

Check server logs for error messages

Verify that the interface path and HTTP method are correct

Content Format Issues

Confirm that the received POST request body is in JSON format

Check that Content-Type is application/json

Verify that JSON parsing is correct

Lyrics Processing Issues

Confirm proper handling of lyrics status field

Check if processing of failed status lyrics is missed

Verify that lyrics content parsing is correct

Alternative Solution

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

Poll Query Results

Use the get lyrics details endpoint to regularly query task status. We recommend querying every 30 seconds.

Lyrics Generation Callbacks

Callback Mechanism Overview#

Callback Timing#

Callback Method#

Callback Request Format#

Status Code Description#

code (integer, required)#

msg (string, required)#

data.callbackType (string, required)#

data.task_id (string, required)#

data.data (array, required)#

data.data[].text (string)#

data.data[].title (string)#

data.data[].status (string, required)#

data.data[].error_message (string)#

Callback Reception Examples#

Best Practices#

Troubleshooting#

Alternative Solution#

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

code (integer, required)

msg (string, required)

data.callbackType (string, required)

data.task_id (string, required)

data.data (array, required)

data.data[].text (string)

data.data[].title (string)

data.data[].status (string, required)

data.data[].error_message (string)

Callback Reception Examples

Best Practices

Troubleshooting

Alternative Solution