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": []
  }
}

Status Code Description

code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - Extension completed
400Bad Request - Parameter error or invalid audio file
401Unauthorized - Invalid API key
413Content Too Long - Audio file too large or duration exceeds limit
429Insufficient Credits - Account credit balance insufficient
500Server Error - Please retry later
msg
string
required
Status message providing detailed status description
data.callbackType
string
required
Callback type indicating current callback stage:
  • text: Text generation complete
  • first: First extension complete
  • complete: All extensions complete
  • failed: Task failed
data.task_id
string
required
Task ID, consistent with the taskId returned when you submitted the task
data.data
array
Extension result information, returned on success
data.data[].id
string
Unique audio identifier
data.data[].audio_url
string
Extended audio file download link
data.data[].source_audio_url
string
Original audio file download link
data.data[].stream_audio_url
string
Streaming audio playback link
data.data[].image_url
string
Music cover image link
data.data[].prompt
string
Prompt/lyrics used for extension
data.data[].model_name
string
AI model name used
data.data[].title
string
Music title
data.data[].tags
string
Music style tags
data.data[].createTime
string
Creation time
data.data[].duration
number
Extended audio duration (seconds)

Best Practices

Callback URL Configuration Recommendations

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

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.