Upload and Cover Audio Callbacks

When you submit a task to the upload and cover 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 covered audio track generated (first stage)
All covered audio tracks generated (complete stage)
Audio cover 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:

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

{
  "code": 200,
  "msg": "First track generated 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] Night city lights shining bright",
        "model_name": "chirp-v3-5",
        "title": "Iron Man (Cover Version)",
        "tags": "electrifying, rock, cover",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      }
    ]
  }
}

{
  "code": 200,
  "msg": "All generated 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] Night city lights shining bright",
        "model_name": "chirp-v3-5",
        "title": "Iron Man (Cover Version)",
        "tags": "electrifying, rock, cover",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      },
      {
        "id": "bd15****1873",
        "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] Night city lights shining bright",
        "model_name": "chirp-v3-5",
        "title": "Iron Man (Cover Version)",
        "tags": "electrifying, rock, cover",
        "createTime": "2025-01-01 00:00:00",
        "duration": 228.28
      }
    ]
  }
}

{
  "code": 400,
  "msg": "Failed to cover audio, invalid upload source",
  "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 - Audio cover completed
400	Bad Request - Invalid upload source or parameter error
401	Unauthorized - Invalid API key
413	Content Too Long - Prompt or style description 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 the current callback stage:

text: Text generation completed
first: First covered audio track generated
complete: All covered audio tracks generated
failed: Task failed

string

required

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

array

Audio cover result information, returned on success

string

Audio unique identifier (audioId)

string

Covered audio file download link

string

Original covered audio file download link

string

Streaming audio playback link

string

Music cover image link

string

Cover prompt used

string

AI model name used for cover generation

string

Covered music title

string

Music style tags

string

Creation time

number

Covered audio duration (seconds)

Best Practices

Audio Cover Callback Configuration

Upload Validation: Verify that the uploaded audio source is valid and accessible
Style Consistency: Ensure cover style parameters match your artistic vision
Quality Monitoring: Implement quality checks for covered audio output
Original Preservation: Keep track of original upload sources for reference
Version Control: Maintain version history of different cover attempts
Content Rights: Ensure you have rights to cover the uploaded audio content

Cover-Specific Considerations

Cover tasks require a valid uploaded audio file
The uploaded audio should not exceed 8 minutes in length
Cover quality depends on the original upload quality
Style transformation may vary based on source material complexity
Consider copyright implications when covering existing music

Alternative Solutions

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

Poll Cover Results

Use the Get Music Generation Details interface to regularly query cover 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 Cover Audio Callbacks

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

Best Practices

Audio Cover Callback Configuration

Cover-Specific Considerations

Alternative Solutions

Poll Cover Results

​Callback Mechanism Overview

​Callback Timing

​Callback Method

​Callback Request Format

​Status Code Description

​Best Practices

​Audio Cover Callback Configuration

​Cover-Specific Considerations

​Alternative Solutions

Poll Cover Results

Callback Mechanism Overview

Callback Timing

Callback Method

Callback Request Format

Status Code Description

Best Practices

Audio Cover Callback Configuration

Cover-Specific Considerations

Alternative Solutions