Skip to main content
When you submit a task to the Add Vocals API, you can use the callBackUrl parameter to set a callback URL. When the task is completed, the system will automatically push the results to your specified address.

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.

Callback Timing

The system will send callback notifications in the following situations:
  • Text generation completed (text stage)
  • First vocal track generated (first stage)
  • All vocal tracks generated (complete stage)
  • Vocal generation task failed
  • Error occurred during task processing

Callback Method

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

Callback Request Format

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

Status Code Description

integer
required
Callback status code indicating task processing result:
string
required
Status message providing detailed status description
string
required
Callback type indicating the current callback stage:
  • text: Text generation completed
  • first: First vocal track generated
  • complete: All vocal tracks generated
  • failed: Task failed
string
required
Task ID, consistent with the taskId returned when you submitted the task
array
Vocal generation result information, returned on success
string
Audio unique identifier (audioId)
string
Audio file download link with vocals
string
deprecated
Deprecated. Original audio file link returned by Suno. This link expires after a period of time and is no longer maintained — do not rely on it for long-term storage. Use the Recovery Audio endpoint to obtain a fresh playable link.
string
Streaming audio playback link with vocals
string
Music cover image link
string
Prompt/lyrics used for vocal generation
string
AI model name used for vocal generation
string
Music title with vocals
string
Music style tags including vocal characteristics
string
Creation time
number
Audio duration (seconds)

Callback Reception Examples

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

Best Practices

Vocal Generation Callback Configuration Recommendations

  1. Use HTTPS: Ensure your callback URL uses HTTPS protocol for secure data transmission
  2. Verify Source: Verify the legitimacy of the request source in callback processing
  3. Idempotent Processing: Ensure processing logic is idempotent as the same taskId may receive multiple callbacks
  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. Stage-based Processing: Handle different callback stages (text, first, complete) with appropriate business logic
  7. Vocal Content Analysis: Implement vocal content analysis and quality assessment for generated tracks
  8. Lyrics Extraction: Extract and process lyrics from vocal prompts for better content management

Important Reminders

  • Callback URL must be publicly accessible
  • Server must respond within 15 seconds, otherwise considered timeout
  • After 3 consecutive retry failures, the system will stop sending callbacks
  • Ensure stability of callback processing logic to avoid callback failures due to exceptions
  • Generated vocal audio URLs may have time limits, recommend downloading and saving promptly
  • Pay attention to vocal content compliance to avoid generation failures due to violations
  • Vocal generation has three stages, each stage will trigger callback notifications
  • Consider implementing content filtering for vocal lyrics and audio content

Troubleshooting

If you don’t receive callback notifications, please check the following:
  • Confirm that the callback URL is accessible from the public internet
  • Check firewall settings to ensure inbound requests are not blocked
  • Verify that domain name resolution is correct
  • 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
  • Confirm that the received POST request body is in JSON format
  • Check if Content-Type is application/json
  • Verify that JSON parsing is correct
  • Confirm that vocal audio URLs are accessible
  • Check vocal audio download permissions and network connectivity
  • Verify audio save path and permissions
  • Note that vocal content must comply with content policies
  • Verify vocal quality meets your application requirements
  • Understand the differences and handling methods of the three callback stages
  • text stage: Only indicates text generation completed, no audio data
  • first stage: First vocal track completed, contains data for one track
  • complete stage: All vocal tracks completed, contains complete vocal track list
  • Implement lyrics extraction from vocal prompts
  • Check vocal content for compliance with platform policies
  • Assess vocal quality and appropriateness for your use case
  • Handle different vocal styles and languages appropriately

Alternative Solutions

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

Poll Query Results

Use the Get Music Generation Details interface to regularly query task status. Recommend querying every 30 seconds.