> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload and Cover Audio Callbacks

> When upload and cover audio tasks are completed, the system will send results to your provided callback URL via POST request

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

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

### 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:

<CodeGroup>
  ```json Text Generation Complete Callback theme={null}
  {
    "code": 200,
    "msg": "Text generation completed successfully.",
    "data": {
      "callbackType": "text",
      "task_id": "2fac****9f72",
      "data": []
    }
  }
  ```

  ```json First Track Complete Callback theme={null}
  {
    "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
        }
      ]
    }
  }
  ```

  ```json All Tracks Complete Callback theme={null}
  {
    "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
        }
      ]
    }
  }
  ```

  ```json Failed Callback theme={null}
  {
    "code": 400,
    "msg": "Failed to cover audio, invalid upload source",
    "data": {
      "callbackType": "failed",
      "task_id": "2fac****9f72",
      "data": []
    }
  }
  ```
</CodeGroup>

## Status Code Description

<ParamField path="code" type="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                            |
</ParamField>

<ParamField path="msg" type="string" required>
  Status message providing detailed status description
</ParamField>

<ParamField path="data.callbackType" type="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
</ParamField>

<ParamField path="data.task_id" type="string" required>
  Task ID, consistent with the taskId returned when you submitted the task
</ParamField>

<ParamField path="data.data" type="array">
  Audio cover result information, returned on success
</ParamField>

<ParamField path="data.data[].id" type="string">
  Audio unique identifier (audioId)
</ParamField>

<ParamField path="data.data[].audio_url" type="string">
  Covered audio file download link
</ParamField>

<ParamField path="data.data[].source_audio_url" type="string">
  Original covered audio file download link
</ParamField>

<ParamField path="data.data[].stream_audio_url" type="string">
  Streaming audio playback link
</ParamField>

<ParamField path="data.data[].image_url" type="string">
  Music cover image link
</ParamField>

<ParamField path="data.data[].prompt" type="string">
  Cover prompt used
</ParamField>

<ParamField path="data.data[].model_name" type="string">
  AI model name used for cover generation
</ParamField>

<ParamField path="data.data[].title" type="string">
  Covered music title
</ParamField>

<ParamField path="data.data[].tags" type="string">
  Music style tags
</ParamField>

<ParamField path="data.data[].createTime" type="string">
  Creation time
</ParamField>

<ParamField path="data.data[].duration" type="number">
  Covered audio duration (seconds)
</ParamField>

## Best Practices

<Tip>
  ### Audio Cover Callback Configuration

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

<Warning>
  ### 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
</Warning>

## Alternative Solutions

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

<Card title="Poll Cover Results" icon="radar" href="/suno-api/get-music-generation-details">
  Use the Get Music Generation Details interface to regularly query cover task status. Recommend querying every 30 seconds.
</Card>