Upload and Extend Audio Callbacks

When you submit a task to the upload and extend audio 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 extended audio track generated (first stage)
All extended audio tracks generated (complete stage)
Audio extension task failed
Error occurred during task processing

Callback Method

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

Callback Request Format

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

{
  "code": 200,
  "msg": "Text generation completed successfully.",
  "data": {
    "callbackType": "text",
    "task_id": "2fac****9f72",
    "data": []
  }
}

{
  "code": 200,
  "msg": "First track extended successfully.",
  "data": {
    "callbackType": "first",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "8551****662c",
        "audio_url": "https://example.cn/****.mp3",
        "source_audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "source_stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "source_image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Continue the beautiful melody of the uploaded audio",
        "model_name": "chirp-v3-5",
        "title": "Extended Music",
        "tags": "extended, original style",
        "createTime": "2025-01-01 00:00:00",
        "duration": 298.44
      }
    ]
  }
}

{
  "code": 200,
  "msg": "All extended successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "8551****662c",
        "audio_url": "https://example.cn/****.mp3",
        "source_audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "source_stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "source_image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Continue the beautiful melody of the uploaded audio",
        "model_name": "chirp-v3-5",
        "title": "Extended Music",
        "tags": "extended, original style",
        "createTime": "2025-01-01 00:00:00",
        "duration": 298.44
      }
    ]
  }
}

{
  "code": 400,
  "msg": "Extension failed, uploaded audio file is corrupted",
  "data": {
    "callbackType": "failed",
    "task_id": "2fac****9f72",
    "data": []
  }
}

Status Code Description

integer

required

Callback status code indicating task processing result:

Status Code	Description
200	Success - Extension completed
400	Bad Request - Parameter error or invalid audio file
401	Unauthorized - Invalid API key
413	Content Too Long - Audio file too large or duration exceeds limit
429	Insufficient Credits - Account credit balance insufficient
500	Server Error - Please retry later

string

required

Status message providing detailed status description

string

required

Callback type indicating current callback stage:

text: Text generation complete
first: First extension complete
complete: All extensions complete
failed: Task failed

string

required

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

array

Extension result information, returned on success

string

Unique audio identifier (audioId)

string

Extended audio file download link

string

Original audio file download link

string

Streaming audio playback link

string

Music cover image link

string

Prompt/lyrics used for extension

string

AI model name used

string

Music title

string

Music style tags

string

Creation time

number

Extended audio duration (seconds)

Best Practices

Callback URL Configuration Recommendations

Use HTTPS: Ensure callback URLs use HTTPS protocol for secure data transmission
Verify Source: Validate 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
Stage-based Processing: Perform appropriate business processing based on different callback stages
Audio Comparison: Compare audio duration and quality changes before and after extension
Upload Validation: Ensure uploaded audio file quality and integrity

Important Reminders

Callback URL must be a publicly accessible address
Server must respond within 15 seconds, otherwise considered timeout
After 3 consecutive retry failures, the system will stop sending callbacks
Please ensure the stability of callback processing logic to avoid callback failures due to exceptions
Extended audio URLs may have time limits, recommend downloading and saving promptly
Uploaded audio files must not exceed 8 minutes, ensure compliance with limits
Extension function will extend audio length while maintaining original style
Music extension has three stages, each stage will trigger callback notifications

Troubleshooting

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

Network Connection Issues

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

Server Response Issues

Ensure the server returns HTTP 200 status code within 15 seconds
Check server logs for error information
Verify that the interface path and HTTP method are correct

Extension Parameter Issues

Confirm that the upload URL is valid and accessible
Check the uploaded audio file format and quality
Verify that the audio file duration does not exceed the 2-minute limit
Confirm that extension parameters (continueAt, etc.) are set correctly

Callback Stage Processing

Understand the differences and processing methods of the three callback stages
text stage: Only indicates text generation complete, no audio data
first stage: First extended music complete, contains data for one track
complete stage: All extended music complete, contains complete music list

Alternative Solutions

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

Poll Extension Results

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

Generate Music

Suno Voice

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

File Upload API

Upload and Extend Audio Callbacks

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

Best Practices

Callback URL Configuration Recommendations

Important Reminders

Troubleshooting

Alternative Solutions

Poll Extension Results

​Callback Mechanism Overview

​Callback Timing

​Callback Method

​Callback Request Format

​Status Code Description

​Best Practices

​Callback URL Configuration Recommendations

​Important Reminders

​Troubleshooting

​Alternative Solutions

Poll Extension Results

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

Best Practices

Callback URL Configuration Recommendations

Important Reminders

Troubleshooting

Alternative Solutions